Re: Documenting from Program Specs

Subject: Re: Documenting from Program Specs
From: Anthony Markatos <tonymar -at- HOTMAIL -dot- COM>
Date: Thu, 5 Feb 1998 11:32:23 PST

Congratulations! You work for a very progressive organization. I have
significant experience working with "program" specs (both as a Systems
Analyst and as a Technical Writer).

You can work off of a program's requirements Spec. A requirements spec.
specifies WHAT the program will do (it is technology independent). A
technical writer can plan his/her work from this input.

You can not work off of a program's design specification. A design
specification specifies HOW the program will work (it is technology
dependent).

It is very common for developers to forgo the requirements spec. and
jump right into a design Spec. (I know that logically this does not make
sense, but that is the way the world works).

Remember, the key input that you need is a clear statement of WHAT the
program is to do.

Sincerely Anthony J. Markatos

>From techwr-l -at- listserv -dot- okstate -dot- edu Thu Feb 5 10:35:23 1998
>Received: from listserv (139.78.114.100) by listserv.okstate.edu (LSMTP
for Windows NT v1.1a) with SMTP id <0 -dot- 69513D40 -at- listserv -dot- okstate -dot- edu>;
Thu, 5 Feb 1998 12:27:23 -0600
>Date: Thu, 5 Feb 1998 13:13:45 -0500
>Reply-To: johnsont -at- freeway -dot- net
>Sender: "Technical Writers List; for all Technical Communication
issues"
> <TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU>
>From: Tom Johnson <johnsont -at- FREEWAY -dot- NET>
>Organization: Star Cutter Company
>Subject: Documenting from Program Specs
>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>
>Wow! Our company is taking a big step in the process maturity model.
>I've been asked to write a manual based on the program specs. Up until
>now, I've felt like software documentation would always be like
>"changing a tire on a moving truck." Now the programmers will build
>prototypes and I will base the documentation on those; kind of a
>parallel development instead of a reactive one.
>
>The goal is to have the documentation completed the same time as the
>program. The programmers will be responsible for making sure the code
>matches the specs and the manual. I remember a brief thread about this
a
>year or more ago and I wondered if it ever works in real life.
>
>Have others found this to be a workable approach? Have you found fewer
>revisions are necessary? Right now I'm looking forward to trying this
>approach. I've also been asked to voice any concerns I have regarding
>usability. Any comments?
>--
>Tom Johnson
>Technical Writer
>Elk Rapids Engineering - A Division of Star Cutter Company
>
>business mailto:johnsont -at- starcutter -dot- com
>personal mailto:tjohnson -at- grandtraverse -dot- com
>- - - - - - - - - - - - - - - - - - - - - - -
>My opinions are still my own.
>
>
>
>
>


______________________________________________________
Get Your Private, Free Email at http://www.hotmail.com




Previous by Author: TW Process Maturity
Next by Author: System Testing and TWs
Previous by Thread: Re: Documenting from Program Specs
Next by Thread: Re[2]: Documenting from Program Specs


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

Sponsored Ads


Sponsored Ads