Re: Documenting from Program Specs

[Penny Staples <pstaples -at- AIRWIRE -dot- COM>]

It's the way we tend to work here, and I like it. It gives me
a chance to ask questions and make suggestions at a point
where the product can still be modified. Often the writer has
a better end-user perspective than the people doing the
actual design and coding. I think the parallel development
approach makes the writer a more integral part of the development
team.

As for problems, I've found that toward the end of the project,
developers may make changes that aren't in the specs or
that don't get into the specs until later. Usually the result of
last-minute new requirements ("ohmigod Sales has been
telling customers that our product can be used underwater!
Can we make it do that? By Thursday?") They may not
remember to tell you about it right away. It hasn't been a
huge problem for me -- you just have to keep your eyes and
ears open. Don't be afraid to insert yourself into conversations
and ask questions.

Penny Staples
pstaples -at- airwire -dot- com

Tom Johnson wrote:
> 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?