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 16:56:32 -0500

Andrew Plato wrote:
>XML and document management systems do not produce information. They
>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
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
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
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,
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
product with impatient users).

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

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
and hand-tweak where you can't automate it. Less work than doing it the
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
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
XML is your silver bullet. Silver is expensive, though, so there's still a
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
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. 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: search engines
Next by Author: Re: Real value (was implementing single-source) (Long)
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