Writing a Software Technical Reference Manual (part 1) - Doing It In Style
(Page 5 of 5 )

Having defined the scope and target audience, you can move on to settingconventions for the document - the tone of language, the formatting ofdifferent levels of text, and so on. This will make filling in the meat(once you have the TOC) a much faster process. You need to decide on:

• Headings: Headings are usually used to indicate the beginning of aparticular segment of information - section heads, sub-section heads andso on. Decide on the levels of information that you want to have (it isusually not advisable to have more than 3) and set styles for them.Avoid stacking headings immediately one after the other. Structure yourcontent so that there is some introductory text after a heading.


• Styles: Your manual will present the users with at least fourcategories of text; the idea behind setting styles is to make it easierto differentiate between them:
  1. Instructional text
  2. Application output/code listings
  3. Screen/module/component labels
  4. Text that the user needs to input
  
  Typically, code listings and input/output text are formatted usingfixed-width fonts like Courier, while other text may be formatted in aneasy-on-the-eyes typeface.


• Indented text blocks: This is text that is peripheral to the pointthat you are making, either background information on a concept you'reintroducing or a warning related to some functional step that you'reexplaining. Indentation helps to separate it from the main body; add alittle icon (like an exclamation or a question mark) to quickly help thereader identify the type of information contained within the indentedblock.


• Tables: Tabulating data is a great way to present data in a snapshot.Set conventions for the look of the tables - bold, centered and titlecase text in the header row - as well as the manner of referencing eachtable.
  
  A good idea for referencing is to have section-wise reference numbers -for example, the reference "Table 1-03" indicates table 3 in section 1.Each table should also have a caption describing the data contained init.


• Diagrams: Engineers love diagrams and flow charts - and an importantpart of your manual is going to be its diagrams. Decide in advance howyou would like to depict the different elements in the diagram; forexample, you could use arrows to indicate the direction of control flowand bubbles to indicate processes. These design elements should be usedconsistently throughout the manual.
  
  Each diagram should have a caption describing what it depicts and areference number - again, it would be a good idea to tie this in withthe section number.


• Screenshots: Screenshots are used either to simply display how ascreen looks, or to indicate its different elements. In the latter case,the callouts labeling the different screen elements will be a prominentpart of the picture, and you should strive to make their arrangementuncluttered. Ideally, all callouts should be on the same side of thescreenshot; however, this may not be always possible. The referencenumber and caption are a requirement here too.


• Bullets and numbering: Bullets and numbering can also help to break upcomplex concepts into simpler, smaller information nuggets. Theconvention here is to use numbering for sequential information only (forexample, steps to perform a task) and bullets for other relatedinformation that is best presented in points instead of a paragraph (forexample, a list of configuration variables).
  
  Bullets also allow you to group together points related to a concept andascribe them levels of importance. Much care and consideration should begiven to the grouping of information in this manner - it could easily beas confounding as useful.


• Terminology: A very, very important rule of creating technicaldocumentation is to be consistent in your use of words. For example, ifyou're using the word "function" to indicate the, well, functions ofyour software, you shouldn't at any point switch to "features","commands", "menu items" or "actions". To this end, make yourself aglossary of the terms that you're going to use right at the start, andstick to them consistently.

At this point, you're ready to actually begin work. Spend some timeanalyzing the structure and components of the application, get togetherwith the developers to get your questions answered, and begin breakingup the manual conceptually into different sections.

I'll assist you in this process in the next, and concluding, section ofthis article, when I'll show the components of a standard table ofcontents for an STRM, and also discuss how to ensure accuracy of yourmaterial via technical and editorial review. Make sure you come back forthat!

Note: Examples are illustrative only, and are not meant for a productionenvironment. Melonfire provides no warranties or support for the sourcecode described in this article. YMMV!

DISCLAIMER: The content provided in this article is not warranted or guaranteed by Developer Shed, Inc. The content provided is intended for entertainment and/or educational purposes in order to introduce to the reader key ideas, concepts, and/or product reviews. As such it is incumbent upon the reader to employ real-world tactics for security and implementation of best practices. We are not liable for any negative consequences that may result from implementing any information covered in our articles or tutorials. If this is a hardware review, it is not recommended to open and/or modify your hardware.

Comments On: Writing a Software Technical Reference Manual (part 1)

>>> Be the FIRST to comment on this article!