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 setting
conventions for the document - the tone of language, the formatting of
different 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 a
particular segment of information - section heads, sub-section heads and
so on. Decide on the levels of information that you want to have (it is
usually not advisable to have more than 3) and set styles for them.
Avoid stacking headings immediately one after the other. Structure your
content so that there is some introductory text after a heading.
- Styles: Your manual will present the users with at least four
categories of text; the idea behind setting styles is to make it easier
to differentiate between them:
- Instructional text
- Application output/code listings
- Screen/module/component labels
- Text that the user needs to input
Typically, code listings and input/output text are formatted using
fixed-width fonts like Courier, while other text may be formatted in an
easy-on-the-eyes typeface.
- Indented text blocks: This is text that is peripheral to the point
that you are making, either background information on a concept you're
introducing or a warning related to some functional step that you're
explaining. Indentation helps to separate it from the main body; add a
little icon (like an exclamation or a question mark) to quickly help the
reader identify the type of information contained within the indented
block.
- Tables: Tabulating data is a great way to present data in a snapshot.
Set conventions for the look of the tables - bold, centered and title
case text in the header row - as well as the manner of referencing each
table.
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 in
it.
- Diagrams: Engineers love diagrams and flow charts - and an important
part of your manual is going to be its diagrams. Decide in advance how
you would like to depict the different elements in the diagram; for
example, you could use arrows to indicate the direction of control flow
and bubbles to indicate processes. These design elements should be used
consistently throughout the manual.
Each diagram should have a caption describing what it depicts and a
reference number - again, it would be a good idea to tie this in with
the section number.
- Screenshots: Screenshots are used either to simply display how a
screen looks, or to indicate its different elements. In the latter case,
the callouts labeling the different screen elements will be a prominent
part of the picture, and you should strive to make their arrangement
uncluttered. Ideally, all callouts should be on the same side of the
screenshot; however, this may not be always possible. The reference
number and caption are a requirement here too.
- Bullets and numbering: Bullets and numbering can also help to break up
complex concepts into simpler, smaller information nuggets. The
convention here is to use numbering for sequential information only (for
example, steps to perform a task) and bullets for other related
information that is best presented in points instead of a paragraph (for
example, a list of configuration variables).
Bullets also allow you to group together points related to a concept and
ascribe them levels of importance. Much care and consideration should be
given to the grouping of information in this manner - it could easily be
as confounding as useful.
- Terminology: A very, very important rule of creating technical
documentation is to be consistent in your use of words. For example, if
you're using the word "function" to indicate the, well, functions of
your software, you shouldn't at any point switch to "features",
"commands", "menu items" or "actions". To this end, make yourself a
glossary of the terms that you're going to use right at the start, and
stick to them consistently.
At this point, you're ready to actually begin work. Spend some time
analyzing the structure and components of the application, get together
with the developers to get your questions answered, and begin breaking
up the manual conceptually into different sections.
I'll assist you in this process in the next, and concluding, section of
this article, when I'll show the components of a standard table of
contents for an STRM, and also discuss how to ensure accuracy of your
material via technical and editorial review. Make sure you come back for
that!
Note: Examples are illustrative only, and are not meant for a production
environment. Melonfire provides no warranties or support for the source
code described in this article. YMMV!
|
/ 11 
