Writing a Software Technical Reference Manual (part 1) - Hard Decisions (Page 4 of 5 )
The scope of this manual will largely depend on the nature of theapplication. While the common goal remains to help install and maintainthe application, the nature and extent of information to be providedwill differ. For example, a software application like an e-mail clientadd-on or Web-based intranet application would contain detailedinformation on software architecture, internal components and APIs. Onthe other hand, hardware like a keyboard or a network card would alsorequire detailed documentation on compatible/supported hardware andsoftware, together with information on configuration and physicalinstallation processes.
Another factor that will affect your scope is the extent to which yourmanual needs to cater to other developers. If further development ofyour application is definitely on the cards, information like theapplication file structure, the variables used, extensibility of thesource code, and even some choice code segments will be a part of themain document. Explaining how the application was developed and thestandards followed may, in fact, even be the overriding aspect in theexplanation of the software and its components.
Defining the scope of your manual is a non-trivial task, and requiresclear understanding of its audience, together with their level ofknowledge. It makes very little sense, for example, to write a manualexplaining the design and internals of the application's APIs when thetarget customer is actually an administrator who's more interested inreading about how to diagnose and troubleshoot problems. A clear profileof the target audience, therefore, plays an important role in decidinghow successful your efforts in building this manual will be.
In order to develop this profile (and, therefore, target the manualappropriately), you should make it a point to find out the customer'sgoals in demanding such a manual. Some customers require the manual formore efficient internal deployemnt of the software; in this case, morestress should be laid on the configuration and tuning sections of themanual. Other customers may ask for this manual so that they may provideother software vendors, or technical partners, with sufficient technicalinformation on the software to build on it further; in this case, adetailed discussion of APIs, control flow and architecture extensibilitywould be appropriate.
When defining the scope, it is also important to give some thought tohow your manual will keep pace with changes in the software as itevolves. A decision involved here is whether for any upgrades delivered,a revised STRM will be delivered as well (the alternative here might beto deliver an appendix capturing the changes in the application from theprevious release). Whatever your decision, it should be clearlyindicated within the introductory sections of the document, withappropriate version numbers in the first case, and references to therelevant sections in the second.
Next: Doing It In Style >>
More Practices Articles
More By Deepa L, (c) Melonfire
/ 10 
