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

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

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 what I can do 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.