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: 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
