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.
> 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.
