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

[mpriestl -at- ca -dot- ibm -dot- com]

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.