TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
