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:Specification Dox From:John Bell <john_bell -at- C-STONE -dot- COM> Date:Tue, 24 Dec 1996 10:46:34 -0500
Mitch Berg asks:
> What do you think is the best way to capture, document, present and
> maintain software system requirements?
I think the best way to start is to identify who the audience of the specs and requirements
docs are, then ask those audience members what it is they need. Quite often the contents
and organization of these types of technical documents are defined by the authors, not
the readers. The authors will do what is easy for them, which may not be enough for the
readers.
IEEE has standards on the organization and contents of requirements, specifications, and
design documents but they are unwieldy. Because the IEEE tries to support many
different types of products with these standards, they include more entries than you may need.
You have to carefully select which elements of their generic standards apply to your
industry and your products. I recommend looking at an IEEE standard just for the education
of it, then devising a standard that works well for your audience.
