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.
Subject:Specs From:Miki Magyar <MDM0857 -at- MCDATA -dot- COM> Date:Thu, 26 Dec 1996 08:46:42 -0700
Mitch Berg asks, "What do you think is the best way to capture,
document, present and maintain software system requirements?"
The best way to capture the specs is to have a fill-in-the-blanks template
that the engineers and programmers can hand back to you. You should
also have access to the design documents and to current engineering
change orders as the product is developed. And the specs should be
reviewed for accuracy and completeness by the designers and test
As to documentation and presentation (are they really different?), I think
it depends on who's going to be using them, and for what purpose. If it's
a marketing thing, then you can use Features! and lots of fancy
footwork. If it's for system administrators or people who have to install
the sucker, then you will want to organize it to suit their needs. Why not
ask them what would be most useful?
I've seen specs documented in a number of different ways - organized
by class (hardware, software, etc.) in a Specifications section of a
manual, by function, in a grey page of lists, and several others.
Maintenance should be the same as the rest of your doc management
process (you do have a process, don't you?!).
If you're stuck with the existing "just OK" docs for now, you can use
them to specify what should be changed, and why, for future docs. It's
always easier to modify an existing doc than to create from scratch,
even if the 'modification' is effectively a new creation.
Good luck, hope this helps.
mikim -at- mcdata -dot- com
They're MY opinions, I tell you! Mine! Mine alone!