![]() Acrobat file (204K) |
![]() ClarisWorks 4 file (84K) |
![]() not available yet |
Technote 1047 | MAY 1996 |
This Technote introduces a series of techniques designed to improve the quality
of technical writing for a developer or programmer audience. It is aimed at
content producers who must produce Release Notes, Readme files, and other forms
of technical writing.
Contents
There are no formulas for producing documentation, particularly if it is aimed at a highly technical audience. A rule of thumb that I've found especially helpful in the creation of any documentation is to allocate time for writing one page per day.
If you factor one page per day into the equation for your project, you'll find yourself in less of a "pressure-cooker" situation as the release date nears. With this very simple step, and a commitment to follow through, you've overcome one of the largest stumbling blocks to creating lucid and comprehensible documentation.
Selecting Your Writing Tools
You want to match the tool to the project. To produce a first draft of any
document, you need to use the tool that you're most comfortable with, i.e., a
speedy word processor or text editor such as BBEdit. After producing the first
draft comes the process of honing the document, a process which may require a
more sophisticated tool, particularly if you are adding figures, tables, or
footnotes.
Here is a very simple stylesheet created in ClarisWorks 4, which you can
download.
This is a simplified version of the stylesheet we use to produce Macintosh Technotes, with three defined heading levels, a style for code snippets or samples, and bullet items. Adapt it to your project's needs.
You can be more productive, and be more likely to achieve your goal of writing one page per day, if you've already constructed the elements you need for a particular piece of documentation in a stylesheet.
Ultimately, as Web publishing becomes the standard, and you find your Netscape browser with a set of Web editing tools built in (such as you have with Adobe PageMill), your reader will also expect to find hypertext links embedded in your paragraphs. That's not just the wave of the future, it's today's reality.
If your document meets the HTML test, it'll have a definite outline form, with level headings, bulleted lists, and a clearly demarcated structure. Figure 1 shows an example of viewing a draft online.
Figure 1: An
example of a draft viewed online
For example, Release Notes accompanying sample code, or an app you've built and want to share, may include the following sections:
Using Color Text for Heading Levels
If your document is going to be viewed onscreen, rather than printed, you can
enhance its readability simply by adding blue and red heading levels, both to
help the reader keep track of sections, and to prevent his or her being
overwhelmed by a solid wall of text onscreen.
There are no rules that I know of for deciding which colors are preferable. Use your own judgment. For a long time, traditionalists disdained using color text in word processing documents, but I find that if my document is eventually to be converted to an Acrobat or another portable document file format, colored text goes a long way towards improving its readability. In fact, color text can even be a very useful method of getting reviewers to mark up a document, as explained in the next section.
Using Color Text in the Review Process
You can eliminate the hassle of printing 10 copies of your document, passing
them around to reviewers, and getting back coffee-stained copies with
indecipherable comments by using a different technique for review. Here are the
steps.
This technique results both in a speedier review process, and a more active involvement by the review team, which will improve the quality of the final document.
Tracking your Work
Just as you would keep a change log of code that you've written, it's important
to keep a log of documents that you've produced, and their status, e.g., out
for review, on hold, released, etc. Here is a little FileMakerPro 3 tracking
database that I've created. The fields are modifiable, so you can create one to
fit your own needs. Figure 3 shows a screen from the tracking database.
Figure 3: The
TechWritingTracker
Download
the FileMakerPro 3 TechWritingTracker by clicking on this icon.
Summary
The wave of the future for technical documentation is the Web, and it's already
here. This change of venue has important consequences for writing and
publishing. Documents that fail to meet the test of online readability will
frustrate readers. The techniques described in this Technote ought to help you
begin to write more Web-friendly documentation.
Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help