Re: Real value (was implementing single-source) - demonstrated!

["Tim Altom" <taltom -at- simplywritten -dot- com>]

Number three would be my choice, too.

You're right about the one-time cost, with some maintenance thereafter. If
you haven't done it before, you might be stunned by how much time and effort
it takes to analyze multiple documents, make a DTD, and test the whole
system. But you're also right in that the results can be equally stunning.
It does interfere somewhat with the "poetic" writers among us who want the
ultimate in freedom.

What you didn't mention was that there is a difference between valid and
well-formed XML. Valid XML needs a DTD, so it's the choice for truly
structured documentation. You can, however, get by with well-formed XML for
small amounts of documentation, if you're willing to give up some
predictability.

DocBook, by the way, is widely considered a magnificent work, but flawed in
its equally monumental complexity. Unless a job is already similarly
complicated, I wouldn't recommend starting with DocBook. I'd rather start
from scratch. Coming down from DocBook is often more difficult than building
upward from the ground.


Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com

----- Original Message -----
From: <mpriestl -at- ca -dot- ibm -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Wednesday, November 22, 2000 5:48 PM
Subject: Re: Real value (was implementing single-source) - demonstrated!


> I'm sort of torn on this issue. I'm completely sold on the value of
> structured writing, however I think technical writing, particularly
> high-tech technical writing, is an unusual subject matter inasmuch as the
> information domain is constantly evolving. This has serious implications,
> since it means that analysing the information domain (to create the DTD)
is
> no longer a one-time cost, but a constant, or regularly recurring,
> activity.
>
> There are three possible solutions to this problem:
>
> 1) Reject XML as a solution entirely. Enforce structure through other
> means, such as writing guidelines for each area, indexing guidelines, and
> so on, and achieve reuse through judicious use of shared files and simple
> cut and paste. This gives you a lot of flexibility, since any of these
> activities is completely open to revision or change using familiar tools
> and existing skills. However, it does mean you have a lot of places where
> inconsistencies or errors can be introduced: there's no guarantee that
> writers will read the guidelines, remember to re-cut and re-paste when the
> original changes, and so on. This solution gives maximum flexibility to
> writers, but also puts a great deal of onus on editors and reviewers to
> interpret and enforce the guidelines.
>
> 2) Use a very generic XML solution (with apologies, I think DocBook is in
> this category). You get enforcement of some structures (ones that are
> common across all technical manuals), but nothing for your specific needs.
> So you still need writing guidelines and ad-hoc processes, and you have
> content that is marked up according to a content domain your reader
doesn't
> care about.  The writer has less flexibility, and the editors and
reviewers
> still have a fair bit of work to do, but this may be enough for your
needs.
>
> 3) Use a layered or architectural XML solution, in which you identify
> general structures (DocBook is fine for this, except that it is oriented
> towards books rather than webs), and then create derived DTDs that more
> specifically define your domain. This is a design pattern known as
> "architectural forms" (there are whole books written about it, so I won't
> go into detail). Basically, it allows you to do a bunch of analysis up
> front (a one-time cost), develop your various doc lifecycle processes up
> front (again, a one-time cost), and then regularly update your actual
> structure to keep it in line with your evolving information domain (a
> regularly recurring cost, but smaller than full-scale analysis because
> you're only identifying deltas from the existing model). This gives
writers
> individual writers a lot less flexibility, but gives a lot of flexibility
> to the writing group: it's harder for a writer to do the lone-wolf thing,
> but much easier to keep  consistent and share knowledge about the domain
> among all writers.
>
> Obviously, I'm pushing for number 3.
>
> On a separate issue, using XML doesn't mean giving up control of how your
> information is structured or presented: it means formalizing how your
> information is structured and presented in such a way that you can change
> one without affecting the other, and communicate your structure to other
> writers   with a minimum of supervision and revision.
>
> If someone presents XML to you as a process solution that removes your
> control of the content, the problem is in the process, not in XML itself.
>
> Speaking on my own behalf,
>
> Michael Priestley
> mpriestl -at- ca -dot- ibm -dot- com
> IBM Toronto Lab



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com or 800-448-4230

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.