For most developers, writing code is the easy part - it'sexplaining it to a customer that's the tough bit. In case you need tocreate a technical manual explaining how your software works, take alook at our handy two-part cheat sheet, which should help make theprocess a little less intimidating.
As the name suggests, the Software Technical Reference Manual (STRM) isconcerned solely with the technical aspects of a software application -how the application is structured, how each component works and how toinstall and configure it. The idea is to give the customer independencein installation, maintenance, administration and further development ofthe application.
From the developer's point of view, the STRM is a blueprint of theapplication that allows him/her to continue development from the lastrelease. The STRM provides developers with the knowledge needed to hitthe ground running when extending or adding on to an application,providing them with the level of detail needed to quickly and rapidlymake 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 adevelopment team deliverable...unless you have a technical writer in theteam with a very sound technical background. A very big advantage ofthis, especially as compared to support documentation like user manualsand help files, is that the time spent on information collection isnegligible; almost all of it is already captured in the planning stagesof the software, in the software requirements document and the softwaredesign document (read more about these at ).
With these two documents in hand and, given the fact that the personwriting the STRM would have been an integral part of the developmentprocess already, actually producing this document becomes a matter of:
Defining the scope of the manual
Setting the conventions
Developing the table of contents
In this article, I'll be focusing on the first two steps, with a list ofthings you should keep in mind when formulating the structure and styleof your manual.