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.
It really is a "chicken and the egg" thing folks. You can't have structure
unless you understand at least something about the content. Both structure
and content evolve as you become more adept with whatever you document.
Structure without content is null, content without structure is void. Way
too many writers out there are either null or void or both.
The best tech writers impose enough structure to give it a direction, change
directions as circumstances warrant, and develop the content based on what
it's supposed to do if it's a spec, and what it really does if it's end user
doc (gross oversimplification). If you write end-user doc, and don't have a
spec, write one if it makes you feel better, or if you think it will help in
future releases. But stop whining about how you can't do your job without
one--it just ain't so.
I don't feel like I've done a complete job until I can write a good spec
that a developer can follow to enhance the product, create an on-line help
system that people actually find helpful, write training materials that
trainers really use, produce manuals that don't get circular-filed, and
create some sales pieces that focus on real features and benefits.
Therefore, I'm never finished-which is OK by me. I still know more about
how the products work than anybody else, why clients would or wouldn't want
to buy it, and how to make it better for the real customers-end users who
need tools to do their jobs.
This chicken is done clucking for now
Connie Giordano
-----Original Message-----
From: MacDonald, Stephen [mailto:Stephen -dot- MacDonald -at- Aspect -dot- com]
Sent: Monday, June 12, 2000 12:28 PM
To: TECHWR-L
Subject: RE: Structure vs. Substance?
Mike Stockman wrote:
> My response to you is this: Keep your structure until I fix the other
> problems. Then we can talk.
On this one, I agree with Dan Emory.
If you could track it back in the history of the doc set's development, lack
of structure was probably the biggest contributor to the "other problems."
Most documentation flaws I have encountered were directly due to poor, or
more commonly, no specifications, market requirements, and software
development process.
