Structure: Was...What sayest me...

Subject: Structure: Was...What sayest me...
From: "Tim Altom" <taltom -at- simplywritten -dot- com>
To: "Chuck Martin" <CMartin -at- serena -dot- com>, "TechDoc List" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 25 Mar 2000 06:56:05 -0500

Maybe we're talking past one another, but structure for us is of vital
importance, no matter what we're writing. We think of EVERY doc as being in
SGML/XML, with a tree structure that must be maintained. Any other way of
doing it is "artistic" or "river rafting" to us, writing that just plunks
down whatever, wherever. An index doesn't save that whirlpool from being
useless. Manuals are not Dummies books. Now, that's not to say that a manual
can't *look* like a Dummies book, because some do. Frame's manual, for one.
But if you look closely, you'll see a tree structure there, too.
Partly-structured isn't good enough for us. It has to be the whole thing.

If you want to know our definition of "structure", check the W3C site for
XML specifications. When Simply Written talks about "structured
documentation", that's what we mean, whether it's going into XML or not. If
a doc is structured properly, it's consistent, easy to maintain, easy to
pass on, easy to transform, and easy to test. It can be pulled apart, its
pieces shuffled with other pieces, and reassembled in new forms. It's even
easier to write, especially when you're working in teams, and if the teams
include distance-workers. If everybody has exactly the same structure to
work from, editing is simpler and projects flow quicker. Single source is
made possible. The only downside to strong structure is that some writers,
accustomed to being able to write like James Joyce, are resistant to it.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com


> It occurs to me: what structure is truly needed in many kinds of
> documentation? For what a lot of people do (software documentation),
> structure isn't really needed for a lot of the material. It's not like
users
> are going to read the document front to back. No, what happens in this
> scenario is that a user needs a particular nugget of information. and
needs
> to know where to find it fast. In this scenario, a "linear" book is no
> different from a hypertext system: a user simply needs access to one
> particular spot, cares less about the overall organization, and will get
> frustrated if that spot can't be found quickly and easily.
and info.





Previous by Author: Re: What sayest me... on Worthless TC Degrees
Next by Author: Re: Re[2]: What sayest me... on Worthless TC Degrees
Previous by Thread: Indexing is always a top priority
Next by Thread: RE: Structure: Was...What sayest me...


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

Sponsored Ads


Sponsored Ads