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:Re: What is a Technical Specifications document? From:Ben Kovitz <apteryx -at- CHISP -dot- NET> Date:Mon, 22 Feb 1999 12:37:49 -0700
Parker, Cassandra M. (EXCH) wrote:
>I'm trying to find out how to write a Technical Specifications document.
>
>Is it usually written by a Tech Writer or the Programmer of an application?
>There is a little debate about this subject in my immediate department.
Alas, the phrase "technical specification" means a lot of
different things to different people.
Here are some documents that people might write during a software
project, intended to be read by people on the development staff
(UI designers, programmers, testers, and technical writers):
Requirements document
Defines the software's problem domain and the effects to be
achieved there. Typically written by the system analyst;
should be of interest to all the developers, and should be
checked by (and therefore understandable to) the customer.
User-interface design
Describes the screens and how they respond to the keyboard and
the mouse; ideally, includes the operating procedures for the
software. Typically written by the UI designer; of interest
to the programmers, testers, and technical writers.
Machine-interface design or Application Program Interface (API)
Describes communication protocols by which the program talks
with other programs or with hardware. Typically written by
the programmer(s) who designed them; usually of interest only
to the programmers and testers.
Program design or architecture document
Describes the overall structure of the program: its main
classes and/or subroutines, how data is organized, and the
flow of control. Typically written by a programmer
(sometimes called an "architect") for other programmers,
though testers often have an interest in this information,
too.
Test plan
Describes actions to try out to verify that the program works
as described in the interface designs and requirements.
Typically written by testers for testers.
Data dictionary
A description of all the data stored by the program, including
tables, columns, data formats, and any other organizational
aspects of interest mainly to programmers. Typically written
by the system analyst and/or the programmers; mainly of
interest to programmers and testers.
I haven't listed the technical writer as the author of any of
these documents. But system analysts and programmers often do
not know how to present the information in these documents
clearly or in a useful organization. For that matter, many of
them do not know what information the readers of the documents
need.
Here is where a technical writer can come in. A technical
writer can work with the person who makes the design decisions
expressed in each document, both to present the information
clearly and to be sure that all the needed information is
covered. (And, in many large companies, to remove the thirty or
forty sections from the template that don't apply to the
project at hand.)
