Re: What is a Technical Specifications document?

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.)

See also http://www.manning.com/Kovitz/Intro.html for some other
variations on who writes the requirements document.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author, _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: Donald Norman and Lotus Notes
Next by Author: Re: Programmer's Functional Specification
Previous by Thread: Re: What is a Technical Specifications document?
Next by Thread: Status of HTML-based Help


What this post helpful? Share it with friends and colleagues:


Sponsored Ads