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.
"You were doing the engineers' and managers' work for them. Next draft,
change them to "would be nice"s, then to "perhaps next release", then
for your final draft, make them "non-goals." You'll save everyone a
lot of time. ;-> <- replace winking smiley with description of sarcastic
intent if you so choose."
Actually, Laura, it is part of my job description to edit functional
specifications. It's a good thing, too, because it is both an edit and a
"review"--it provides me with several things:
1. I get to have input on the design (I'm the first "usability
tester"). If I think the way the software is described as working
is cludgey, or otherwise flawed, I can say so before the design
is implemented. This means a better chance at getting changes (tho'
of course you still have to work on getting respect for your
opinion!--more on that later).
2. I get to find out what the products are going to be as early as
possible (don't expect to be told _anything_), and can therefore
get a head start on planning the manual, as well as the preliminary
3. Because it is _their_ work, they are interested in listening to
my questions, which otherwise may be considered an interference with
their coding later, when I'm writing the manual and need to know
4. If I re-write their stuff so that it is clear (but also clear that
I don't understand, and have therefore changed the meaning), they have
to explain to me what I don't understand. This wouldn't normally
happen until the technical review of the manual, much later, when it
may have more serious consequences.
5. It gives the writer the opportunity to participate more closely with
the development team, and this communication provides the basis for
greater mutual understanding and respect.
Interestingly, there are software life cycles where the documentation has to
be written before a line of code is written, which would require even more
participation from technical writers.
Gwen (the originator of the quote, above) Gall (ggall -at- ca -dot- oracle -dot- com)
P.S. I forgot something else:
6. And everyone KNOWS that the documents were cr*p before I edited
them, and my appreciation level goes WAY UP!