FW: Documentation planning (was Re: FW: Extreme Technical Writing )

Subject: FW: Documentation planning (was Re: FW: Extreme Technical Writing )
From: Syed Ahmed <SAhmed -at- DKSYSTEMS -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 10 Jan 2002 10:59:55 -0600


My second tech writing project was a contract position where I was the lone
tech writer with a company that had absolutely no existing documentation or
specs, aside from the application itself (yet another handicap of
startups!). I began documenting each widow, field, menu option, and any
other feature of the app without understanding the actual business processes
that drive them. Although it involved a lot of tedious work, this
"preliminary" doc provided the starting point to began investigating.

My next step was to propose the creation of a "standard" set of
documentation that accompanies most software (depending on the platform and
development tools), to the development staff and the sponsoring business
groups. As it was a web based app, the docs I suggested were:

1. User/Getting Started Guide
2. Installation Guide
3. Administration Guide
4. Database Reference Guide

This initial proposal is my archetype approach, and served as the starting
point for discussion where, as a group, the development and business side
reps decided what was necessary, what was nice to have, and what was
completely unnecessary. If your client doesn't know what they want, I found
that making recommendations forces them to think about what they really need
before the work begins. For example, during this proposal meeting (which
turned into a brainstorming session), they also realized they wanted entity
relationship diagrams as well. This meeting was also an excellent
opportunity to identify the priorities of each doc/diagram, as well as

Based on their newly discovered requirements, I began the documentation
process. Unfortunately, due to a lack of structure and direction from the
client, I did more research and leg work than I would have done in a
traditional development environment, but my input and counsel were highly
valued, since I knew much more about the product than many of their

This type of a documenting environment can be frustrating and a struggle,
but starting with a "tabula rosa" can also be enjoyable, because you have
much more freedom in terms of the presentation format and the actual content
of each help doc. Tech writers could use a little creative freedom now and
then to keep our sanity, so this might be one way to see the good in your
tough predicament ;).


Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: RE: Unknown abbreviation...
Next by Author: RE: IMAP method
Previous by Thread: Re: KDE Help
Next by Thread: Alone from the start (was: Documentation planning)

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

Sponsored Ads

Sponsored Ads