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

Under The Microscope - 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


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:
  1. Defining the scope of the manual
  2. Setting the conventions
  3. Developing the table of contents
  4. Production
  5. Review
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.

>>> 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: