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

Doing It In Style - 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.

TABLE OF CONTENTS:
  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
SEARCH DEV SHED

TOOLS YOU CAN USE

advertisement
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!

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

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort
   

PRACTICES ARTICLES

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