Re: technical documentation for software

Subject: Re: technical documentation for software
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 29 Dec 2000 00:59:20 -0500

SANDY BAKER wrote:

> Does someone have advice about gathering and writing technical documentation
> for software?

Start with the resources on the raycomm.com list associated with this list.
Look at some of the sites and books recommended there, and at the archive
of discussions on this list.

> I've been asked to devise a plan for documenting the software for a
> 'fast-paced environment'. Documentation is the LAST thing the developers
> want to hear about when they've got three weeks to develop and test an
> application.

If the application is more than a couple of hundred lines, involves more
than two developers, or is inherently complex, three weeks is nonsense.

> We're trying to establish what the minimum requirements for documentation
> are:
> * Service Request (actually the User's document)
> * Application Requirements
> * System FlowChart
> * Data Dictionary: Description of Files and Databases (DBAs are
> actually doing this part)
> * Technical Information needed for Testing, Installation, Maintenance
> * Application (Version) Release

The above list is what the development manager might ask for. For some apps
and development styles, it is appropriate. (I've never seen flowcharts that
were actually useful, but..). For other styles, you might need an ER model
for the database or a formal analysis of the object structure or ...

I'd say you also need some sort of design document. It's conceivable the
design is clear from what you've listed, but I'd be amazed if it were so.

What else do you need? User manual? Marketing info? Training material?
Info on interfacing this to other products? On running it with a different
DBMS? Administrator's guide? Something on the security considerations? ...

What does it take to fit into your target environment? On Unix, I'd expect
a man page for every program, every user-callable function, every file
format, ... Windows users may expect online help in their format. The web
has other constraints.

Are there legal or contractual requirements on this? Must you meet ISO 9000
standards? Do you, or your client, have legal constraints on the information
this software will manage, e.g. an obligation to keep health records or other
personal info secure? If so, your docs (and everything else) must show "due
diligence" in meeting that requirement.

> I'd also like some hints for getting this info from developers to tech
> writers, since tech writers are responsible for getting this all down on
> paper.

Hire smart tech writers, people with the ability to learn fast, think on
their feet in your complex environment, and with enough technical
background in your field to have a starting point. Be prepared to pay
well or you won't get them.

Then support them. Treat them as part of the development team. Make it
clear to programmers that they are responsible for helping document
their programs.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by an
anonymous satisfied subscriber since 1994.

---
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: anyone else in the same boat?
Next by Author: Re: Revision History in Readme?
Previous by Thread: RE: technical documentation for software
Next by Thread: Re: technical documentation for software


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


Sponsored Ads