Re: Real value (was implementing single-source) (Long)

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

With apologies, I messed up the formatting the first time I sent this.

Andrew Plato wrote:
>XML and document management systems do not produce information. They
>*process* information. Only a human being who understands concepts can
>*produce* information. Garbage in, garbage out.

In my opinion, an XML document type should accurately describe the
structure, semantics, and constraints of an information domain. In this
respect, they do more than process information - they provide a template
for new authors in an existing domain to follow.

So you need someone who understands the information domain, as well as
understanding DTD syntax, to design the DTD. The DTD *is* information - it
is information about the domain you're working in. For example, if you're
documenting Java APIs, the information that a method can be public,
protected, or private, and that a class can contain a method but a method
cannot contain a class.

>These large documentation management systems are touted as flexible, but
they
>really are not. They hinge on a rigid database structure where all
information
>must be tagged, blocked, and categorized. Not condusive to rapid,
fundamental
>change. Not condusive to creativity. Not condusive to flowing,
concept-based
>documents. Not condusive to profit-centric businesses. Many of them
consume
>more time in the management and maintenance than they save in document
>production.

There's plenty of crap out there. Plenty of it was written in Word, too. So
what? You are blaming XML instead of the people who abuse it. XML is
ideally suited to rapid, fundamental change, to creativity, and even to
flowing, concept-based documents (if you're into that sort of thing - good
for a 1.0 product where the users might actually read it, crap for the help
system of a mature product with impatient users).

Categorizing the info is not an end in itself. Once you've categorized the
info, it's searchable by category. That buys something for your users: they
can say "tell me what APIs return the Address object", instead of searching
on "Address" and getting hits all over the library, including every
frontmatter comment form.

If your categories change (and I'd certainly expect them to, over time) you
can write XSLT transforms that map your old information to new categories,
and hand-tweak where you can't automate it. Less work than doing it the
old-fashioned way (all by hand), and more value to the customer.

>XML may be useful at large companies. It may very well have value.

The size of the company has nothing to do with it - it's the size of your
information that matters. If your information is big enough that it's hard
to search, and you understand it well enough to identify useful information
and repeating patterns, XML is your silver bullet. Silver is expensive,
though, so there's still a cost-benefit analysis to do.

>But I
>caution anybody considering it - do your job well FIRST, then find ways to
make
>it better. If you can't handle the basics of technical writing, it will
not get
>any better with an advanced documentation system.

Absolutely true. And never automate if it's cheaper not to. That said, I'm
good enough at my job that I'm downright excited about how I can do it
better with XML.

Speaking on my own behalf,

Michael Priestley
mpriestley -at- acm -dot- org
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.