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:Supporting Documentation for Software Development From:Candlin Dobbs <SturtivC -at- KOCHIND -dot- COM> Date:Tue, 18 Nov 1997 14:59:00 -0600
Dear Assembled Tech writers:
I find myself needing to put together standards and a plan for
documentation to support a major internal development effort which
implements a refinery-specific data warehouse.
I'm a technical writing consultant (and the lone writer here). I've done
lots of different kinds of docs over the years (systems docs to on-line
help for users) but usually I can rely on some pre-existing standards
or the users knowing what they want. Right now the developers are so
busy that it's hard to get them to stop long enough to do some
definition. And we all know that defining the problem is essential to
being able to plan the writing of it --
I'm thinking that they will need five basic categories of documents:
1) Project planning documents
This is the project plan, issues log, bug log, minutes from
status meetings, etc. Some of this I've already got in place.
2) Design Documents
Functional and Technical Specs, minutes from meetings with
users, anything that documents user requirements. This is very
scattered and they need some guidance about what they should be
documenting.
3) Systems/Technical Documents
Standards (e.g. naming standards for data items), systems
overviews, procedures and how to's for technical issues (to do data
cleanup, backups, etc.)
4) User Docs
5) Training Docs
I know how to approach 4 and 5 and probably 1, but what about 2 and 3?
Does anyone have suggestions about
*standards for specs and other technical docs
*the best approach to take
*places on the web to look for standards, hints, etc.
*anything else I should suggest that they document
We need to document things well enough that another site can use the
same tool and get it set up similarly as well as getting the in-house
developed pieces in place.
Thanks for your thoughts -- I'd be happy to do a summary of your
responses if I get a lot of responses...
