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

Subject: Re: Real value (was implementing single-source) (Long)
From: mpriestl -at- ca -dot- ibm -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 10 Nov 2000 17:56:11 -0500

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
>really are not. They hinge on a rigid database structure where all
>must be tagged, blocked, and categorized. Not condusive to rapid,
>change. Not condusive to creativity. Not condusive to flowing,
>documents. Not condusive to profit-centric businesses. Many of them
>more time in the management and maintenance than they save in document

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
>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. or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more 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 for more resources and info.

Previous by Author: Re: Real value (was implementing single-source) (Long)
Next by Author: Re: The "Too Familiar" problem
Previous by Thread: Re: Real value (was implementing single-source) (Long)
Next by Thread: Re: Real value (was implementing single-source) (Long)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads