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:Summary: Documenting from Program Specs From:Tom Johnson <johnsont -at- FREEWAY -dot- NET> Date:Tue, 17 Feb 1998 08:38:42 -0500
A short time ago I asked for advice on writing manuals based on program
specifications and prototypes. After finishing up some loose ends on
another project, I?ve had a chance to review the great advice and
anecdotes from those who have replied. My original post is at the
bottom, if you missed it the first time.
The general consensus is that the approach can work, but there has to be
good communication between the programmers and the writers. Changes are
going to occur and there has to be a good process for making sure
programmers notify the writers about those changes. There may or may not
be fewer revisions. Several writers urged getting involved early in the
process.
>From Kris Olberg:
>Talk with the programmers several times a week to discover what's changing and how.
>I've never found this approach to decrease revisions. In fact, it may increase them, but I have no facts to back up that assertion. However, the resulting documentation was highly accurate.
>From Beth Agnew:
>Your team must also adhere to good change control procedures, and one they?ve made the plan, STICK to the plan.
Everyone who replied offered good information. My thanks go out to Kris
Olberg and Beth Agnew and the rest who replied.
My original post:
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.
