Re: Documenting System While Under Developme

Subject: Re: Documenting System While Under Developme
From: Jim Grey <jimgrey -at- IQUEST -dot- NET>
Date: Wed, 17 Apr 1996 08:54:00 EST

Karen Gaignard (keg0 -at- ATSOAA1 -dot- EM -dot- CDC -dot- GOV) frets:
>The system I am trying to document is still very much under development.
>Most things are not hooked up yet, so I cannot see more than the initial
>screen for each menu choice in the module I have been asked to do first.
>And cannot even see how those work, because they don't do anything yet.
>Also, what I can see is in the middle of being changed. What I am trying to
>do is write based on what the developer of the module is telling me will be
>there and how it will work. This seems like a lot of wasted effort and
>frustration to me, but I have been told to start documenting the system now.

>Can someone(s) give me some advice/techniques for how to handle this?
>Detailed advice is much appreciated.

>Sorry if this is a ridiculous question, but I am frustrated!

Your question is NOT ridiculous. It is key.

If you wait until the system is better developed before you begin writing,
you probably won't have enough time to finish the documentation before the
system ships.

If you start writing now, documenting what works and making your best guess,
based on the developer's projections, at documenting what doesn't work, you
will probably have to rewrite portions of your document to reflect eventual
reality. Doing work twice is no fun. I agree, it's frustrating. You'll
have to add more time to your estimate to cover the rework you'll certainly
do. (Your management may have raised eyebrows over it, but hey, that's
reality!) In my experience, however, this method gives you a greater chance
of finishing the document before the system ships.

You are fortunate to work with a developer that tells you what the system is
intended to do. Many of us do not have that luxury! I frequently encounter
screens that don't work yet. I have decent luck guessing at the screen's
eventual functions and at least outlining documentation based on my guess.
The screen may change several times before release, and I dutifully change
my outline every time. When I find out that the screen is pretty much
finished, I fill in the outline with text.

Ideally, you and the developer would work from a robust design document.
You'd be able to write a good share of the documentation, save perhaps
screen captures, based on the design document, and be assured that your
document would be pretty close to the final product. Ah, idealism!

jim grey |beebeebumbleandthestingersmottthehoopleraycharlessingers
jimgrey -at- iquest -dot- net|lonniemackandtwangin'eddiehere'smyringwe'regoingsteadyta

Post Message: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe: LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner: ejray -at- ionet -dot- net

Previous by Author: Re: Message Confirmation?? Let's get the facts straight
Next by Author: Re: Terminology
Previous by Thread: Re: Documenting System While Under Developme
Next by Thread: Re: Copyright of Posted Works

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

Sponsored Ads