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 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!
Peace,
jim
--
jim grey |beebeebumbleandthestingersmottthehoopleraycharlessingers
jimgrey -at- iquest -dot- net|lonniemackandtwangin'eddiehere'smyringwe'regoingsteadyta
|http://www.iquest.net/~jimgrey
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
