Writing a Software Technical Reference Manual (part 1) - Under The Microscope (
Page 2 of 5 )
As the name suggests, the Software Technical Reference Manual (STRM) is
concerned solely with the technical aspects of a software application -
how the application is structured, how each component works and how to
install and configure it. The idea is to give the customer independence
in installation, maintenance, administration and further development of
the application.
From the developer's point of view, the STRM is a blueprint of the
application that allows him/her to continue development from the last
release. The STRM provides developers with the knowledge needed to hit
the ground running when extending or adding on to an application,
providing them with the level of detail needed to quickly and rapidly
make leveraged changes to an application's code tree.
The audience, therefore, is technically knowledgeable in both cases -
either the customer's MIS department or developers who want to enhance,
improve or modify the application.
Given the content and the audience, this document is usually a
development team deliverable...unless you have a technical writer in the
team with a very sound technical background. A very big advantage of
this, especially as compared to support documentation like user manuals
and help files, is that the time spent on information collection is
negligible; almost all of it is already captured in the planning stages
of the software, in the software requirements document and the software
design document (read more about these at ).
With these two documents in hand and, given the fact that the person
writing the STRM would have been an integral part of the development
process already, actually producing this document becomes a matter of:
- Defining the scope of the manual
- Setting the conventions
- Developing the table of contents
- Production
- Review
In this article, I'll be focusing on the first two steps, with a list of
things you should keep in mind when formulating the structure and style
of your manual.
/ 11 
