Home arrow Practices arrow Page 4 - Writing a Software Technical Reference Manual (part 1)

Hard Decisions - Practices

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.

  1. Writing a Software Technical Reference Manual (part 1)
  2. Under The Microscope
  3. A Little Knowledge...
  4. Hard Decisions
  5. Doing It In Style
By: Deepa L, (c) Melonfire
Rating: starstarstarstarstar / 11
February 05, 2003

print this article


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.

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: