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:Kimberly Lyle-Wilson <klylewilson -at- HOTMAIL -dot- COM> Date:Thu, 5 Feb 1998 12:59:28 PST
I have had mixed success with this approach. I think it depends largely
on the company and the project.
In one case, documenting from specs was very difficult because 1) the
specs were really vague and didn't address some information that was key
to my audience; 2) the developers were tight-mouthed; and 3) the
finished product had strayed a bit from the specs.
In another case, documenting from specs was downright laughable. The
product changed significantly on a daily basis, there were no real specs
(just a proposal), and the project was in total chaos most of the time.
This might account for why the project was late and over budget. (And
why I nearly went crazy in four short months!)
On my current projects, I am well-integrated into the development team,
and the specs are very detailed. I joined the team near the end of the
last project, but still found the specs fairly matched the finished
product. As suggested by another reader, getting involved in the
development process really helps. I don't attend development meetings
with the codeheads, but I attend all the meetings between development
and users, which helps me understand the audience I will be writing for,
beyond what the specs say. Even so, I will only be doing about 50-75
percent of the documentation in advance. I will complete the remainder
after the product is submitted to the users for sign-off. Minor changes
may occur after that, but my documentation should be finished by final
sign-off (a couple of weeks later).
Good luck with your project.
Technical Writer, Information Systems
The Weather Channel
>> <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
>>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?
>>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.
>>Send commands to listserv -at- listserv -dot- okstate -dot- edu (e.g., SIGNOFF
>>Search archives at: http://listserv.okstate.edu/archives/techwr-l.html,
>Get Your Private, Free Email at http://www.hotmail.com