When performing a technical edit on a peer's work, follow the guidelines on this page.
Provide Positive Reinforcement
You should provide plenty of positive reinforcement in your comments. If a paragraph is well-written, say so. If a section is accurate and clear, say so. You'll be amazed at how effective even a few positive comments are. A spoonful of sugar really does make the medicine go down. Starting off your comments with a positive global comment can make all the difference.
Search for Omissions
Good technical editors search not only for technical mistakes but also for technical omissions. Technical editors often focus on what is present and neglect what is missing.
Avoid Vague Comments
Bad technical editors provide vague comments; good technical editors provide clear comments. For example, the following comment is worthless and rude:
The preceding comment only becomes useful when followed by an explanation of what is correct; for example:
You were close—actually, the subtropical ridge is usually centered near latitude 32. Suggest Replacement Text
To increase the odds of a writer accepting a suggestion, good technical editors suggest replacement or alternate text. For example, the following comment does not provide any replacement text, so a hurried writer might skip over it:
This has to do with the subtropical ridge. Ask Michelle to explain.
The preceding suggestion necessitates some time-consuming research. The following comment has a far greater chance of being incorporated:
I'd suggest something like the following: "Tropical cyclones typically curve around the perimeter of the subtropical ridge."
Editing and the Documentation Process > Technical Editing a Peer's Work 261
Technical Editing a Superior's Work
If you are editing the work of a superior (either a manager or a more senior scientist), follow the guidelines on this page.
Provide Thanks
Provide a quick preface to your edits, thanking your superior for the opportunity to edit, preferably without sounding too obsequious. For example, the following is just too gushy:
It is a thrill to work with someone as famous as you. However, a comment such as the following is appropriate:
I learned a lot about artificial insulin research from reading this paper. Make it clear that you would be honored to review subsequent drafts of the document.
Phrase Edits as Suggestions
Phrase your edits as suggestions whenever possible. Obviously, a misspelled word is a misspelled word and should be handled as a straightforward correction. However, you should handle more subjective matters with care. For example, the following is far too direct for a superior:
Eliminate the opening sentence.
Rephrasing an imperative order as a question or suggestion will serve your career better; for example, consider the following improvement:
How about if you omit the opening sentence and use that strong second sentence as your opening?
Ill-
262 Editing and the Documentation Process > Technical Editing a Superior's Work
Copyediting a Colleague's Document
A copy editor is a wonderful resource that many organizations simply cannot afford. Sometimes, you must act as the de facto copy editor on a project because no one else is available. Sometimes you must take that critical last look at a document to catch any embarrassing mistakes before outsiders do. If you find yourself in this situation, here are a few suggestions for performing a quick copy edit:
• View the draft in the same medium as the target audience will. For example, if the target audience will read the document in PDF, review a PDF version of the draft, not a paper version.
• Check the table of contents. Does it include all the chapters and top-level section headers?
• Check all the headers and footers in the book. Are they consistent? Are page numbers displayed? Are any pages missing? If this is a book, do all chapters start on an odd-numbered page? Do the page numbers sequence correctly? (Don't laugh—page numbering mistakes are common, particularly in the transition from the table of contents to Chapter 1.)
• Get access to the word-processor sources for the document. Run a spell-checker on them. If a grammar-checker is available, run it. Most spell-checkers don't check for context. For example, if a writer used there instead of their, most spell-checkers won't report a mistake.
• Check tables and figures. Do they all contain captions? Do all titles and captions match up with their corresponding tables and figures? (In other words, are any captions in the wrong place?) Do all tables and figures have a numerical label, such as Figure 11-2 or Table 7-1?
• Verify that you placed trademarks or registered trademarks correctly. Consult with your corporate attorney, if necessary.
• If you only have enough time to review a tiny section of the document, evaluate the section or chapter that will draw the most readers.
Spreading the Wealth
Suppose a writer asks 10 technical editors to review a 300-page document. In all probability, only one or two of them will make it past the first 50 pages. Technical editors have limited time and limited attention spans. To improve coverage, the wise writer assigns different sections of the book to different technical editors.
Copyediting Your Own Document
Foxes should never guard the chicken coop, inventors should never act as their own quality assurance department, and writers should never edit their own work. Nevertheless, when no one else is available, you must become your own best editor. This is a suboptimal situation; you are simply too familiar with your own work to do a good editing job, so you will skip over mistakes that would have been obvious to another reader.
One of the best tricks for editing your own work is to read it aloud. This technique helps you find missing words and awkward sentences. It also does a great job of catching run-on sentences. (When you start to run low on oxygen, you've found a run-on.)
Reading aloud generally won't help you find spelling mistakes, but a spell-checker certainly will.
Another technique—one that sounds ludicrous but that some professional editors swear by—is to "read" the text backwards. Actually, you don't really read the text as much as you view it. The theory is that, when reading forwards, your mind coasts rapidly and carelessly through familiar text. By viewing the same passage backwards, you suddenly see it in a different way. Obviously, this technique isn't for everybody.
You will generally find more errors in passages that you wrote a while ago than in passages you recently wrote. An old saw—one that has some merit—suggests throwing your first draft in a drawer and forgetting about it for a while. If you are writing a lengthy document, consider putting yourself on a delayed editing schedule, where you edit a chapter six weeks after you've written it.
The preceding techniques are emergency stop-gap measures. Good writing, like good engineering, ultimately requires input and feedback from multiple parties.
Ill
264 Editing and the Documentation Process > Copyediting Your Own Document
Media for Technical Editing
Some engineering teams edit paper copies of documents. Other teams edit online.
For paper edits, editors take out their trusty red pen (nicknamed "Satan") and write comments directly on the hard copy. The writer eventually scoops up all the marked-up copies and incorporates the revisions. On the second round of editing, the writer should return the editors' original comments so that they can verify changes. The advantages of this approach are as follows:
• It is simple to implement.
• Many professional writers prefer this because it gives them more control.
• If the document being reviewed will be delivered to readers in hard copy, then reviewers see the document as readers will.
In recent years, many teams have switched to online editing. The technology for online editing ranges from fairly simple (each reviewer marks up a separate copy of the source document) to rather elaborate (using collaboration software, reviewers can see and comment on other reviewers' comments). The advantages of online editing are as follows:
• Most technical reviewers can type much faster than they can handwrite. Since the keyboard is mightier than the pen, reviewers tend to supply comments that are lengthier and more useful. Furthermore, writers never run into problems reading illegible handwriting.
• Depending on the technology, writers can sometimes simply indicate that they accept the change request, and it will be automatically implemented.
• Online editing saves paper.
Most high-end word processors provide a change-bar feature, which automatically flags any text that has changed since the previous version. Whether editing hard or soft copy, the change-bar feature helps focus editors' energy on the second pass.
Editing and the Documentation Process > Media for Technical Editing 265
Bug-Tracking Systems
Most engineering organizations use a bug-tracking system to monitor defects in a product. Many organizations also use these systems to monitor defects in documentation. The benefits of such a system are pretty much the same, whether you are tracking engineering or documentation defects. Namely, the key advantages are as follows:
• Unlike human memory, a bug-tracking system won't forget bugs.
• A bug-tracking system lets managers prioritize bugs to help focus effort on the most serious defects.
• A bug-tracking system records fixed bugs to prevent duplication of effort.
The disadvantage of a bug-tracking system for monitoring documentation defects is that it sometimes takes a disproportionately long time to open a new bug report. For example, a person who finds a misspelled word might avoid reporting it through a bug-tracking system if it takes five precious minutes to open a new bug report. After all, it is oh-so-much-easier to e-mail the writer about the mistake. I'm not saying that the easy way out is virtuous, but the goal is to detect and correct as many bugs as possible, and the bug-tracking system might hinder that goal.
I recommend using a bug-tracking system to report and monitor documentation bugs after the initial release of the document. Prior to the initial release, I recommend using the hard-copy or online editing techniques noted in this chunk.
QUANTUM LEAP
To reduce the number of documentation defects in early drafts (no matter how they are reported), always put your best effort out for review. In other words, spell-check and reread your document prior to submitting it. Too often, technical editors focus their reviewing energy on easy stuff (such as misspelled words) rather than on substantial technical issues. To keep technical editors focused, give them less low-hanging fruit to harvest.
266 Editing and the Documentation Process > Bug-Tracking Systems
A Process for Editing
Editing is essentially a quality assurance process for documentation. Therefore, the wise project team approaches documentation as an engineering process requiring a set of checks and balances. The process for creating documentation should ideally contain the following well-defined phases:
1. Writer creates documentation specifications.
2. Writer generates Draft 1.
3. Literary editor performs a literary edit on Draft 1.
4. Writer incorporates literary edit comments and generates Draft 2.
5. Team performs a technical edit on Draft 2.
6. Writer incorporates technical edit comments and generates Draft 3.
7. Team performs a technical edit on Draft 3.
8. Writer incorporates technical edit comments and generates Draft 4.
9. Copy editor performs a copy edit on Draft 4.
10. Writer incorporates copy edit comments and generates final document.
The preceding assumes a perfect world filled with plenty of time and resources. Unfortunately, the perfect engineering world is as attainable as a perfect vacuum. Many engineering teams skip plenty of the preceding steps to allow the writer more time for writing.
Enough Time to Review
Common sense suggests that the quality of edits and reviews increases as you give reviewers more time. However, common sense does not apply here. An old managerial adage states, "Work contracts or expands to fill the time allotted." My experience suggests that this adage is dead-on. For example, reviewers allotted three days to edit a 150-page document will do just as good a job as reviewers allotted three weeks. Naturally, there are limits—you can't expect someone to review a 500-page book in a day.
Technical reviewers often generate conflicting comments. When this happens, get all reviewers together over the phone or face-to-face. Don't let reviewers debate this sort of thing in e-mail as the discussion often turns contentious and unproductive. People's voices are far more polite than their e-mail messages.
Beta Tests for Documentation
In a beta test, real-world customers play with an almost-finished product and tell the inventors what they like and what they don't. Good engineers use this valuable input to improve their products.
Good engineering organizations also beta-test documentation. Unfortunately, most engineering organizations don't beta-test documentation optimally and end up with worthless comments such as, "The documentation was okay." If you want worthwhile beta-test comments on documentation, you have to go after those comments aggressively.
If the documentation is distributed in HTML format or as online help, build a documentation feedback button onto every page. When a beta-tester presses this button, a form should pop up asking for suggestions. Keep this form extremely simple; don't weigh it down with lots of extraneous information such as the beta-tester's title. In fact, the best form simply asks for suggestions, period.
If the total number of Best-testers is small, try to identify each individual who will read the beta documentation. At the beginning of the beta test, contact beta-testers and determine whether they are responsive to further questions about the documentation. (If you can get them to agree at the beginning, you'll be more likely to get good feedback later.) Assure beta-testers that all their feedback (good and bad) is quite helpful. Then, keep the lines of communication open. Get feedback while an idea is fresh in the mind of a beta-tester, so an instant medium such as IM is just about perfect.
Don't rely on surveys at the end of a beta-test to get documentation feedback. A closing survey will typically garner only general comments. For example, if a respondent rates your documentation as a 4 on a scale of 1 to 7, how exactly would you change your documentation? If your organization insists on a closing survey, try to get respondents to identify missing topics.
If your organization is financially blessed, offer financial carrots to beta-testers who provide significant feedback.
Determining Where to Spend Documentation Resources
When communicating with beta-testers, make sure you determine which documents they read most often. Then, after beta-testing finishes, focus your documentation resources on improving these documents. Fish where the fish are biting.
1
268 Editing and the Documentation Process > Beta Tests for Documentation
Summary of Editing and the Documentation Process
When performing any sort of edit, follow this general advice:
• Remember that you are editing the work of a fellow human and that most humans are sensitive to criticism.
• Find something to praise about the document, even if it's really bad; if there is actually something good about the document, well, all the better.
When performing a technical edit (technical review) on a document, focus on the following:
• Forget that you are you; instead, imagine that you are someone in the target audience for this document. Determine what that person would need to know.
• Perform any documented steps just as a user would. For example, if this is a software installation manual, find suitable hardware and use the documentation to install the software. Don't read between the lines—treat the text literally, doing exactly what it tells you to do.
• Determine what is missing from the manual.
• Provide clear criticism so that the writer knows how to fix the problem.
When performing a literary edit or a copy edit on a document, focus on the following:
• Follow the advice in Section 2 of this book, which details best technical-writing practices. Pass along this advice (diplomatically) to the writer. For example, identify passive-voice sentences that should be changed to active voice.
• Review captions to make sure that they are informative and accurate.
• Search for context problems that spell-checkers would miss.
• Identify passages that are unclear.
• Prior to editing, jot down a few topics that you expect to find in the book. Then, make sure that you can find all of them in the index and in the table of contents.
Editing and the Documentation Process > Summary of Editing and the Doc. Process 269
I CHAPTER 19
Fonts and Typography
Although it is difficult to pick the best tourist attraction in New Jersey, my personal favorite is its never-ending supply of diners. For those of you who don't vacation in New jersey, a diner is a friendly, inexpensive restaurant that features book-length menus, often with hundreds of entries. Sadly, the massive menus overwhelm many patrons who end up selecting something more dorky than fulfilling."
Every modern computer system provides dozens, even hundreds, of fonts. Most computer users ignore this cornucopia and stick with the safe defaults chosen by their word processing software. This is a real pity. After all, fonts can give gravity to a serious document or leaven a casual document. Picking the right fonts can make your documents look more professional, just as picking poorly can detract from your message.
On the Other Hand, Mashed Potatoes Are Comforting
Fonts don't have to be exotic to be interesting. I don't want to suggest that you should set a serious technical document in a novelty font such as Papyrus or Park Avenue just because it would give your document a distinct look. Novelty fonts can punch up a birthday card or an advertisement, but they have no place in the kinds of scientific documents that you are writing.
Until a few decades ago, a chapter on fonts would not have appeared in a book for mere mortals. In the old days, engineers and scientists wrote the words and left all font decisions to trained printing professionals. Nowadays, though, anyone can conjure font changes with a few mouse clicks. This chapter helps you click wisely.
1. Burgers and fries.
2. Latkes with apple sauce. Try the cheese blintzes, too.
1-
Serif and Sans-Serif Fonts
If you look very closely at the words in this sentence, you'll see tiny horizontal and vertical notches popping out from the ends of most of the letters. Just to make it a little more obvious, I've blown up a lowercase p in Figure 19-1.
serif
*
serif serif
FIGURE 19-1 This lowercase p contains three serifs.
Notice the tiny horizontal lines at the base of the p and the tiny little hook in the upper left. These tiny lines are called serifs. Some fonts have them, and some don't. Fonts in which most of the characters have serifs are called (not surprisingly) serif fonts. Fonts in which none of the characters have serifs, such as the character shown in Figure 19-2, are called sans-serif fonts.
P
FIGURE 19-2 This lowercase p contains no serifs.
Table 19-1 summarizes three popular serif fonts. The Weight column refers to the relative thickness of the lines and curves constituting each character. For example, printing the let-
272 Fonts and Typography > Serif and Sans-Serif Fonts
ter o in a heavy-weight font expends more ink than printing it in a light-weight font. Many of these fonts provide a boldface version that is exceptionally heavy.
TABLE 19-1 A Few Popular Serif Fonts
Example
Weight Comment
Garamond The quick brown fox
Light This font suggests elegance and preci
sion. It features ornate serifs (look closely at the T), which strike some readers as old-fashioned.
Palatino- The quick brown
Linotype fox
Medium This is a good choice for technical
documents. Characters in this font are a bit wider than in the other two fonts, so text consumes more space.
Times New The quick brown fox.
Roman
Heavy This font also makes a good choice for
technical documents, but because of its ubiquity, documents in Times New Roman do not stand out.
Table 19-2 summarizes three popular sans-serif fonts.
TABLE 19-2 A Few Popular Sans-Serif Fonts
Verdana The quick brown fox
Heavy This font gives hard-copy documents a
distinctive look. Notice how wide it is relative to the other two fonts in this table. If space is at a premium, this font would not be a good choice.
Many systems use Arial and Times New Roman as the default fonts, so users with typographic inertia often just go with these fonts. Both fonts are sturdy choices. However, since they are ubiquitous, documents that use them do not stand out. If you want to imbue a document with a distinctive look or brand, then you must choose nondetault fonts.
Fixed-Width versus Variable-Width Fonts
All the fonts examined so far—whether serif or sans serif—have been variable-width fonts. In a variable-width font, each character occupies only the horizontal space it needs. In the following example, notice how B and i snuggle up tightly:
BiBi
Every character in a fixed-width font (also called a monospace font), whether brawny or svelte, consumes exactly the same amount of horizontal space. Thus, naturally skinny characters end up with a lot of white space around them. For example, in the following example, notice how much blank space is between each pair of letters:
BiBi
Fixed-width fonts use horizontal space less efficiently than variable-width fonts. Table 19-3 describes two popular fixed-width fonts.
TABLE 19-3 Two Popular Fixed-Width Fonts
Fixed-width fonts are generally less readable than variable-width fonts. In addition, large blocks of text in fixed-width fonts don't look good. Nevertheless, you should use them to display the following:
• programming source code or command lines
• mathematical or scientific equations (although you probably need a special font for many equations)
• values that must line up, such as in a spreadsheet or database
m
274 Fonts and Typography > Fixed-Width versus Variable-Width Fonts
Serif and Sans-Serif in Hard Copy
When producing hard-copy documentation, a simple formula for typographic success is as follows:
• Use a serif font for all body text, which includes the following:
- paragraphs
- lists
- table cells
• Use a sans-serif font for all header text, which includes the following:
- chapter titles and section headers
- table headers
- table and figure captions
- figure callouts
- page headers and footers, plus page numbers
• Use a fixed-width font for all special elements, which include the following:
- equations
- software commands or code
In other words, a document should typically contain a grand total of only three fonts—a serif font, a sans-serif font, and a fixed-width font. For example, you might use Palatino for all body text, Verdana for all header text, and Lucida Console for all special elements. If you were to use only a single font throughout the document, section headers and table captions would tend to hide. Following the three-font formula makes it easier for readers to find what they are seeking.
Serifs Are Sweet Noise on Paper
Many centuries ago, typographers discovered that serif fonts were more readable than sans-serif fonts. This is rather astonishing because serifs are essentially noise-extraneous particles strewn over a clean surface. (Can you think of any other instance In which adding noise to a system makes it more comprehensible?) Although sans-serif fonts look cleaner than serif fonts, the readability evidence in favor of serif fonts is overwhelming. Nearly every hard-copy novel is set in a serif font.
Serif and Sans-Serif in Soft Copy
When producing soft-copy documents, you should rely entirely on sans-serif fonts.
Serifs Strike Sour Chords Online
In hard-copy documents, serif fonts are more readable. However, in soft-copy documents, sans-serif fonts are more readable. The reason has to do with the resolution of the different media. Most hard-copy published documents are printed at 1,200 dots per inch. However, even the best monitors can render soft-copy documents at only 125 dots per inch or so. At such a low resolution, serif fonts look smudged, but sans-serif fonts still look clean and sharp.
Most people choose one of the following two strategies for using sans-serif fonts in soft-copy documents:
• Apply a single sans-serif font throughout the document.
• Apply two different sans-serif fonts; for example, use Arial for body text and Verdana for headers.
Even if you choose the latter strategy, you must still rely on additional characteristics (such as font size, indentation, and color) to differentiate body text from header text. Different sans-serif fonts generally look rather similar; most readers cannot easily differentiate Arial from Verdana. Using a different color is much more obvious than using a different sans-serif font.
Arial is a very popular choice right now for online documentation, particularly on machines running Microsoft Windows. That is because Arial was designed specifically for soft-copy documents. (Most fonts were designed for hard-copy documents.)
Mixed Media
Sometimes you must provide the same document in both hard copy and soft copy. In such cases, you should determine which medium is more popular and apply fonts accordingly. When hard copy and soft copy are equally popular, I usually use the rules for hard-copy documents. One other possibility is to generate two different versions from the same source. The only disadvantage to doing so is that page numbering might differ between the two versions, which can cause confusion.
12
276 Fonts and Typography > Serif and Sans-Serif in Soft Copy
Font Height
Font height is measured in a peculiar unit called a point, where 72 points = 1 inch
Given the preceding definition, you might expect a 36-point character to be exactly 0.5 inches tall. You silly logician, you! In fact, every 36-point character is far shorter than 0.5 inches. However, measuring from the bottom of the font's lowest letters (for example, £ or j) to the top of the font's tallest letters (for example, Z or /) does yield a height of exactly 0.5 inch. See Figure 19-3.
WJ.
5 inches
FIGURE 19-3 A 36-point font is 0.5 inches from the lowest point to the highest. Best Font Sizes for Hard Copy
The following are a few general guidelines for setting font sizes in hard-copy documents:
• Set all body components (paragraphs, lists, and table cells) to the same font size.
The size you pick should be somewhere between 10 and 11 points, inclusive. For example, don't set paragraphs to 10 points and bulleted lists to 11 points.
• Sans-serif fonts look a little bigger than serif fonts of the same point size. For this reason, set the following components one point smaller than body components:
- table headers
- table and figure captions
- figure callouts
For example, if you set your body components to an 11-point font, set your table headers to a 10-point font.
• Leave big deltas between different section header levels. I like to leave a difference of at least three points (four points is better) between the font sizes of a first-level header and a second-level header. For example, readers can easily distinguish
Fonts and Typography > Font Height 277
between an 18-point first-level header and a 14-point second-level header, but the difference between an 18-point and a 16-point font is much harder to distinguish.
Larger Fonts Appeal to Older Readers
One of the central theorems in technical communication is to be clear. For this reason, good technical communicators consider the age of their readers when making font decisions. When writing for the over-40 set, never pick a body font smaller than 10 points. Older readers greatly prefer an 11-point body. Remember-your readers can't click a menu to make text bigger in a hard-copy book.
Best Font Sizes for Soft Copy
PDF and HTML are the two most popular formats for online documentation distribution.
When creating PDF documents, absolute font sizes are not important since readers can easily change the effective font sizes through a simple menu selection. Nevertheless, relative fonts sizes are still important, so the size guidelines for hard copy are relevant for PDF documents.
When creating HTML documents, you must choose between one of the following strategies for setting font sizes:
• Set font sizes explicitly through HTML tags or through cascading style sheets (CSS).
• Do not set font sizes; instead, let users set them through browser controls.
The first strategy—setting font sizes (and other font characteristics) explicitly—offers the greatest control. For example, with a CSS, you can tell the browser to render all paragraphs in 11-point Arial. However, this control is somewhat illusory because you cannot control the screen resolution at which readers will view the document. For example, 11-point Arial looks sharp on an 800 x 600 screen but becomes intolerably tiny on a 1600 x 1200 screen.
The second strategy—letting users pick font sizes—is generally preferable for technical documents. This strategy permits users the luxury of adjusting the font to meet their eyes' needs. In addition, this strategy is much easier to implement than a CSS.
Hi
278 Fonts and Typography > Font Height
Italics and Boldface
Most fonts provide italic and boldface (or just bold) variants. Both draw attention to a particular word, so when would you italicize and when would you bold? This page provides a few guidelines. Note that these are only guidelines, not hard-and-fast rules. Whatever guidelines you choose, apply them consistently within a document or documentation set. For example, if you introduce new terms with boldface in one chapter, don't introduce new terms with italics in another chapter.
Boldface
Boldface stands out more than italics. Therefore, if you really want to draw readers' attention to a word or phrase, put it in boldface. Don't overuse bold—a little bold goes a long way. If a page contains too much boldface, the impact of boldface fades. Note that many headers appear to be in boldface even when they aren't. (Large fonts often look bold.) I recommend using boldface for the following passages:
• when introducing new terms in a paragraph, as in the following passage: Polyprotic acids contain multiple acid hydrogen in each molecule.
• in the portion of a command-line dialog that a user enters verbatim; for example, notice that the user literally enters prime and 23 in the following passage:
$ prime
Enter an integer: 23
23 is prime.
Italics
I recommend using italics for the following:
• the title of a book, article, or other copyrighted source
• a foreign word or phrase not found in an English dictionary
• in software documentation, any nonverbatim word or passage that the user must enter; for example, in the following command, the user must enter an integer (not the literal word integer):
dexprime integer
Note that italics show up badly online, so many Web writers use boldface for emphasis rather than italics.
II::.
Consistency and Convention
Whatever fonts you choose, apply them consistently. For example, if you start off with Palatino for all body text, then stick with it throughout the entire document. In addition, you should also apply boldface, italics, and fixed-width fonts consistently.
How do you make sure that you apply fonts consistently? The key is to work with a strict word-processing template" rather than blindly pressing the Ital ic or Boldface button. For example, a good word-processing template should define components with names such as the following:
• Emphasize
• NewTerm
When a writer needs to emphasize a passage, instead of trying to remember whether to bold or italicize, the writer simply "tags" the text with the Emphasize component. In this way, all emphasized passages end up in the same font.
One of the benefits of the preceding approach is that it simplifies global changes. For example, suppose the Emphasize component is defined as italic. If a new editor arrives and decides that the corporate standard for emphasized passages should be boldface, it is a simple matter to implement this change just by redefining the Emphasize component.
Font Conventions
Many manuals contain a "Font Conventions" section identifying the purpose or usage of each font in the manual. For example, such a section might indicate that 10-point Courier bold represents text that the user must enter verbatim.
On one hand, "Font Conventions" sections remove potential ambiguities. On the other hand, if a manual requires such a section, then the fonts in that manual were probably not clear enough.
I
3. This is often called an SGML approach. SGML, or Standard General Markup Language, is a superset of HTML.
280 Fonts and Typography > Consistency and Convention
True-Type versus PostScript Fonts
Two different font technologies dominate the personal computer world. Almost all the fonts on a Windows PC or Macintosh rely on one of the following standards:
• True-Type fonts, which have the .TTF file extension on Windows-based PCs
• PostScript (also called PostScript Type 1 or just Type 1) fonts, which have the .PFM and .PFB extensions on Windows-based PCs
Which category is better? True-Type fonts get more use because Windows PCs come fully stocked with them. However, most professional graphic artists prefer the superior quality of PostScript fonts. PostScript fonts come in tandem files, with one file (the .PFM file) holding the screen version of the font and the other (the .PFB file) holding the printer version. In some cases, font creators produce both a True-Type and a PostScript version of the same font.
A single document should always use a single font technology. In other words, never mix True-Type and PostScript fonts in a single document. Mixing font technologies often causes printing problems.
Fonts and Typography > True-Type versus PostScript Fonts 281
Summary of Fonts and Typography
Ask yourself the following questions about the font choices in your document:
• What is the output medium for this document?
- If the output medium is hard copy, have you used serif fonts for body and sans-serif fonts for headers?
- If the output medium is a computer screen, have you used sans-serif fonts for everything?
• Are the fonts big enough to be legible?
- Will older readers have trouble reading these fonts?
- If this is an HTML document, will readers on high-resolution monitors be able to see these fonts? Can readers change the size of fonts?
- If this is a hard-copy document, is the body text set in 10- or 11-point type? Are the headers noticeably larger than the body text?
• Are fonts used consistently throughout the document (and document set)?
- Do the settings for first-, second-, and third-level headers change?
- Do you use italics and boldface consistently?
- Do you use consistent fonts for headers and footers?
• Are the fonts obtrusive? Fonts, like journalists, should tell the story without calling attention to themselves.
282 Fonts and Typography > Summary of Fonts and Typography
CHAPTER 20
Punctuation
Please forgive this grammatical intrusion, but many people have trouble using the following punctuation marks correctly:
• commas
• dashes and hyphens
• semicolons
• periods
• colons
• quotation marks
This appendix does not provide a comprehensive look at these punctuation marks; it only summarizes their most common uses within technical prose. If you want to learn every nuance, see a style manual, such as the Chicago Manual of Style.
Musical Punctuation
If words are notes, then punctuation marks are rests. Musically speaking, you might think of punctuation in the following way:
• A comma is a quarter-note rest.
• A dash is a half-note rest.
• A semicolon is a three-quarter note rest.
• A period is a full-note rest.
If sheet music isn't your thing, don't worry—all will become clearer in the next few pages.
Punctuation 283
Commas
English is a rather flexible language, and there is very little to stop you from placing a comma just about anywhere. A comma signals a short pause or division. If you are uncertain whether to use a comma, just read the sentence out loud and place a comma anywhere your voice rests briefly. For example, when reading the following sentence out loud, your voice should pause briefly just after the word life:
Although carbon is one of the critical elements of life, a tiny percentage of carbon atoms are naturally radioactive.
Technical prose often contains conditional sentences. In a conditional sentence, use a comma to separate the condition from the consequence. For example, the following conditional sentence contains an explicit iff and then:
If the pressure drops by more than 10 mb in an hour, then a severe storm is on the way.
The previous sentence contains an explicit then, but in many conditional sentences, the word then is implied. In such sentences, the comma is critical to helping the reader identify the implied then. For example, in the following example, notice the comma after hour:
If the pressure drops by more than 10 mb in an hour, a severe storm is on the way.
As noted in Chapter 7, technical communicators prefer bulleted lists to embedded lists. Nevertheless, if you do create an embedded list with more than two items, place commas after each element in the list except the final element. For example, in the following example, note the comma after the first element (oranges) and the second element (lemons):
Three types of citrus fruits are oranges, lemons, and limes.
Good technical prose is built for speed; commas act as speed bumps. As a rule of thumb, sentences within technical prose should rarely contain more than two commas. Sentences containing more than two commas are ripe for editing.
1
284 Punctuation > Commas
Dashes and Hyphens
Dashes come in the following two flavors:
• em dashes (—), which are as wide as the letter "M" in a given font
• en dashes (-), which are as wide as the letter "N" in a given font
The en dash is the grammatical fifth Beatle—most people just want it to go away. Its only common use in technical prose is in numerical spans, such as the following:
The hybrid engine increases gas mileage 30-50%.
Like commas, em dashes are signals for the reader to pause. Readers pause longer for em dashes than for commas. Em-dashes often travel in pairs. The text between a pair of em dashes often provides a quick definition, as in the following example:
Iodine is a halogen—a nonmetal with a single electron to donate—and a common allergen.
Hyphens
A hyphen is a very short dash (-), even narrower than the en-dash. Word processors automatically supply hyphens to split multisyllabic words at the end of a physical line. You explicitly supply hyphens to string together a group of unsplittable words. For example, the hyphens in the following example unite four words into one compound noun:
Crank the handle as you would a jack-in-the-box.
The hyphens in the preceding example are essentially the opposite of commas; commas cause readers to slow down, but hyphens cause readers to speed up. In the preceding example, the reader mentally runs the hyphenated jack-in-the-box together as one word. You also use hyphens to join a multiword adjective preceding a noun; for example, consider the hyphens in the following example:
The corpus callosum helps convert short-term memories into long-term memories.
Be careful—do not use a hyphen unless the modified noun follows the multiword adjective, for example, the following example correctly contains no hyphens because the noun memories does not follow either of the multiword adjectives:
The corpus callosum helps convert memories from short term to long term.
Ill a:'
Semicolons
Use a semicolon to connect two closely related, complete sentences. A semicolon and a period are essentially interchangeable; however, the semicolon suggests the marriage of a perfectly matched couple, almost as if the writer couldn't bear to separate the two thoughts with something as harsh as a period. In the following sentence, notice that the two sentences are so closely related that the writer could have reversed their order:
Hydrogen is the only element without a neutron; each hydrogen atom contains only a proton and an electron.
Good writers often place transition words such as however and therefore immediately after a semicolon. Remember to place a comma immediately after the transition word. For example, consider the following:
A stable helium nucleus contains two protons and two neutrons; however, several unstable helium isotopes contain more than two neutrons.
You may place a transition word in the middle of a sentence. In such instances, put a comma before and after the transition word, as in the following example:
A stable helium nucleus contains two protons and two neutrons; several unstable helium isotopes, however, contain more than two neutrons.
You may place multiword transition phrases (such as on the other hand or for example) immediately following a semicolon, as in the following example:
On one hand, Java enables truly portable programs; on the other hand, Java programs often run slowly.
Never place a conjunction (such as and or but) after a semicolon; for example, the following grammatically improper sentence requires a comma instead of a semicolon:
Assembly language programs run quickly; but they are difficult to code.
Occasional use of semicolons helps your writing look more professional. Overuse of semicolons tends to look a little sophomoric.
,
286 Punctuation > Semicolons
Periods
As you know, you place a period at the end of most sentences. However, the humble period also serves a few other uses in technical prose, which this page describes.
Parentheses provide a splendid opportunity to misuse periods. If you place a full sentence within a pair of parentheses, then place the period just inside the closing parenthesis, as in the following example:
Hurricanes have sustained winds of at least 65 knots. (In the Pacific Ocean, hurricanes are called typhoons.)
If you insert a phrase (not a complete sentence) within a pair of parentheses, then do not place a period within the parentheses. For example, notice that the period appears after the closing parenthesis in the following example:
Hurricanes have sustained winds of at least 65 knots (74 miles per hour).
You place a period after an abbreviation but not after an acronym, as in the following examples:
Dr. (abbreviation—ends with a period) DBMS (acronym—does not end with a period)
Exclamation Points
In recent decades, editors and pundits have vilified the exclamation point so much that writers who dare use it are now generally sneered at. The feeling among the literati is that exclamation points are a cheap trick to infuse excitement. Real writers, they say, build excitement through words. While I don't believe that inserting exclamation points is a capital crime (hey, I've put several exclamation points in this book), I'd recommend using them sparingly.
Colons
Within technical prose, use a colon to introduce a list, table, or figure that will immediately follow. For example, the following passage correctly uses a colon to introduce a bulleted list:
Water has the following properties:
• It is an excellent solvent.
• It becomes less dense below 4°C.
If the list, table, or figure does not immediately follow its introduction, then terminate the introductory sentence with a period rather than a colon. For example, in the following passage, notice that the introduction occurs a few sentences prior to the start of the list:
Water has the following properties. Note that water is the only compound to have these critical properties. Without the second property, most aquatic life would die.
• It is an excellent solvent.
• It becomes less dense below 4°C.
The sentence introducing a list should always appear on the same page as the start of the list. However, it is okay for a table or figure to appear on a different page than the sentence that introduces it. In this case, the sentence introducing the table or figure should end with a period rather than a colon, even if there is no additional text after the introductory sentence. For example, compare the right and wrong ways of introducing a figure that appears on a different page:
Figure 8 on page 24 illustrates packet passing in a token ring network, (right) Figure 8 on page 24 illustrates packet passing in a token ring network: (wrong)
ft:
288 Punctuation > Colons
Quotation Marks
In fiction, quotation marks bound the beginning and end of a spoken line, as in the following example:
Woody said, "And, I think what we've got here is a dead shark."
Technical prose offers very few opportunities for such juicy dialog. However, quotation marks allow technical authors to bound an exact quote from another written source, as in the following example:
Newton's First Law of Motion states, "Every object in a state of uniform motion tends to remain in that state of motion unless an external force is applied to it."
A solid alternative to quotation marks is to place verbatim text on separate lines, indented as follows:
Newton's First Law of Motion states the following:
Every object in a state of uniform motion tends to remain in that state of motion unless an external force is applied to it.
Some sources advise writers to indent only those quotes that are longer than ten physical lines. Personally, I also find it useful to indent much shorter quotes.
You may place quotation marks around a particular word or phrase to indicate that you are using that word in a special or nonstandard way. For example, the following quotation marks are a little wink to the reader to indicate that you realize that robots are gender-neutral:
The robot was dressed in a tuxedo when "he" answered the door.
Avoid using quotation marks that might hamper clarity. For example, consider the quotation marks in the following sentence:
To remove the locked file, issue the command, "rm *.lck."
Punctuation > Quotation Marks 289
The preceding example might fool the reader into thinking that the closing period is a required part of the command. When there is even a remote chance of confusing readers, remove the quotation marks and do one of the following instead:
• Mark the special text with a different font.
• Place the special text on a separate line.
The latter option is the better approach. For example, the following version removes any possible confusion about what command to enter:
To remove the locked file, issue the following command: rm *.lck
Straight Quotes versus Curly Quotes
Many word processors provide the following two kinds of quotation marks:
• "straight quotes," which look a little like the number 11
• "curly quotes," which look a bit like the numbers 66 and 99
Generally speaking, you should use curly quotes. The only common exception is when documenting sample program code. For example, note that the following code contains straight quotes:
printf("The answer is %d.", my answer);
II!
290 Punctuation > Quotation Marks
GLOSSARY
abstract A brief summary of a lengthy proposal or lab report.
active voice A sentence in which the subject acts on the object. For example, Cheetahs chase zebras is an active-voice sentence because the subject (cheetahs) verbs the object (zebras). Active- voice sentences are usually shorter, clearer, and more powerful than passive-voice sentences. In addition, most readers for whom English is a second language prefer active voice sentences. Compare to passive voice.
audience The people who will read your document or view your Web site. The audience members for a Web site are also called visitors.
block diagram A figure typically consisting of a set of rectangles with embedded labels. In some block diagrams, an artist draws arrows between the rectangles to connect related structures visually. In other block diagrams, the artist stacks rectangles vertically to symbolize a hierarchy.
bullet The typographic mark—usually a filled circle or square—that denotes the start of a new element in a bulleted list.
bulleted list A list in which each element begins with a bullet. Unlike a numbered list, the elements in a bulleted list have no specific order. In other words, if you rearrange the elements of a bulleted list, the list would still have the same meaning. Compare to numbered list.
business plan A proposal aimed at getting money to start a new business or expand an existing business.
business proposal A proposal aimed at selling a new idea (typically, for a new product) within an existing company.
S
Glossary 291
callout A combination of a textual label and a pointer (a line segment or arrow). A callout points to a particular part and gives it a name. Compare to embedded label.
caption A brief description of a figure, typically prefaced by a number. By custom, captions appear just below figures. The captions associated with a table are sometimes called tides.
chunk A short, discrete unit or lesson on a particular topic. Typically, each chunk starts at the top of a new page.
color blindness A condition in which people (usually men of European background) have trouble distinguishing among certain colors.
conjunction A word (such as and or but) that connects two related thoughts within the same sentence. Compare to transition.
context-sensitive help A kind of online help system that automatically provides the relevant help information based on the user's current situation. With context-sensitive help, users do not have to search for the appropriate help file.
cookbook-style manual A manual similar to a culinary cookbook in which each topic consists of a list of materials followed by a numbered list of instructions.
copy editor A type of literary editor who looks for errors in spelling, punctuation, and grammar. Compare to developmental editor.
cover letter A formal business letter that introduces an attached document (such as a resume or proposal).
CSS Abbreviation for Cascading Style Sheets. A CSS enables Web developers to maintain a distinct and consistent look across an entire Web site.
design spec In some industries, another name for a low-level technical spec.
developmental editor A type of literary editor who acts as a sort of writing tutor to improve organization and writing style. Compare to copy editor.
doc project plan A planning document that summarizes an entire documentation set to be written. A doc project plan explains how each manual will fit into a cohesive whole.
HI
292 Glossary
doc spec A planning document that summarizes a single manual to be written. Doc specs usually define the manual's audience, length, and approach. Good doc specs also provide a detailed outline and schedule.
dynamic content Program-generated Web information. Unlike static content, dynamic-content can change depending on who is visiting the site or what a given visitor wants to do with the site.
elevator speech A very short oral presentation to a venture capitalist or banker in which an entrepreneur describes an idea for a new company.
element A numbered or bulleted item within a list.
embedded label A label placed directly on the part of a figure that it describes. Compare to callout.
endnote Scrap of information (often a citation) that appears in a note at the end of a document. Endnotes and footnotes typically contain the same sort of information, but footnotes appear on the source page, and endnotes appear at the end of the document.
establishing shot A graphic that shows an entire scene or the exterior of an object. Photographers, cinematographers, and graphic artists like to present an establishing shot prior to graphics that provide details.
FAQ Abbreviation for frequently asked questions. FAQs are a staple of newsgroups and other Internet communications. As the name suggests, a FAQ is a list of common questions and their answers.
fixed-width font A font in which each character consumes exactly the same amount of horizontal space. Compare to variable-width font.
font A graphically consistent set of characters.
footnote 1
functional spec In many industries, another name for a high-level technical spec.
1. A numbered note (like this one) that appears at the bottom of a page. Formal scientific and technical writing reserves footnotes for certain kinds of citations. However, more casual scientific and technical writing may also use footnotes for digressions. In general, technical documentation shouldn't contain too many footnotes.
Glossary 293
guide A manual more advanced than a tutorial, intended for more experienced readers. Good guides generally teach topics by presenting a series of examples, moving from moderately easy to more advanced ones.
header A title within a document. The definition of header has shifted somewhat in the last couple of decades. Originally, a header was any title, including a chapter title. Now though, many people do not think of a chapter title as a header and believe that only those sections or subsections within a chapter can be called headers. Headers are hierarchic; thus, documents typically contain first-level headers, second-level headers, and so on.
Hello World example The simplest possible example. A Hello World example should typically be the first example in any technical book. The phrase comes from the first example in a book called The C Programming Language by Brian Kernighan and Dennis Ritchie.
high-level technical spec A detailed internal document aimed at a multiple departments (for example, sales, marketing, and documentation). A high-level technical spec summarizes a product about to be developed.
home page The Web page intended to serve as a starting point for visitors to a Web site. All Web sites should contain a home page, although it is not a given that visitors will browse to the home page before viewing other Web pages. Compare to secondary pages.
HTML Acronym for Hypertext Markup Language. The bread-and-butter encoding language of the Internet, consisting of simple tags (such as <LI> for a list) and plain text. HTML is a subset of a larger encoding scheme called SGML (Standard Generalized Markup Language).
imperative verb A verb that acts as a command. For example, in the sentence Put the cap on the tube, the word put is an imperative verb.
jargon The words, phrases, and acronyms that practitioners use when communicating among themselves but that are unknown to most nonpractitioners.
layout The geometric arrangement of graphic elements (graphics and text) on a virtual or physical page. This is sometimes called composition.
literary editor A person who reviews documentation with an eye toward the writing itself rather than the technical content. Copy editors and developmental editors are two types of literary editors. Compare to technical editor.
Ill
294 Glossary
low-level technical spec A detailed internal document aimed at the engineers on a project who will be implementing a new product or technology. Such specs provide the blueprints for how the engineering team should implement the product or technology.
manual A document that teaches readers how to perform a task, use a product, or master a technology.
monospaced font Another name for fixed-width font.
nonverbal manual A manual that contains only graphics and no words.
numbered list A list in which each element is preceded by an integer. The elements must be listed in a particular order. If you can change the order of the elements in the list, then it should be a bulleted rather than a numbered list.
online help Generally, any documentation presented in soft-copy format. However, most people now reserve the term online help to mean a particular kind of soft-copy documentation that provides quick, concise explanations of how to accomplish specific tasks.
pace The rate at which a document presents information. A fast-paced document presents a lot of new information per page, while a slow-paced document presents only a little new information per page. Slow-paced documents spend more time explaining assertions than fast-paced documents.
page template Instructions that produce a consistent layout across a set of Web pages. Strict adherence to a good page template helps produce professional-looking Web sites.
parallelism Grammatical and logical consistency among all the elements in a list. Elements within a list should be completely parallel. For example, if the first element in a list is a singular noun, then all subsequent elements in the list should be singular nouns.
parenthetical clause A digression, example, or elaboration within a sentence. A parenthetical clause is bounded by a pair of commas, parentheses, or dashes.
passive voice A sentence in which the subject is acted upon by the object. For example, the sentence Zebras are chased by cheetahs is in passive voice because the subject (cheetahs) is verbed upon by the object (zebras). Use passive-voice sentences sparingly in technical and scientific writing. Compare to active voice.
: K
Glossary 295
PDF Abbreviation for PostScript Display Format. With the right software, authors can convert documents written in any word processor to PDF. Users with the right software (such as Adobe Acrobat Reader) can view or print PDF documents.
point In typography, a unit for measuring the height of fonts, as measured from the top of the highest letter to the bottom of the lowest. One point is 1/72 of an inch high. The point is one of the slipperiest units of measurement in the entire mathematical world; for example, every letter in a 12-point font is shorter than the expected 1/6 inch.
pointer In layout, anything that directs a reader's eyes. For example, an arrow is a pointer because readers will look in the direction that the arrow is pointing.
PowerPoint Software manufactured by Microsoft (and part of the Microsoft Office Suite) that helps organize presentations.
preproposal A brief summary—either written or oral—communicated to reviewers prior to creating a full proposal. Use the preproposal to test the waters.
proposal A written request to do something—for example, to perform research, start a company, or develop a program—in exchange for money or other resources.
Question-and-Answer (Q-and-A) Format A style of documentation in which each header is a question, which the body text answers.
readability quotient A mathematical formula for estimating the appropriate educational level of a document's audience. For example, a certain readability quotient might determine that a given document is appropriate for sixth graders.
reference manual A manual in which details are presented as a series of discrete topics. Reference manuals usually provide rather terse descriptions compared to guides or tutorials.
release notes A document popular in software products that typically describes the new features of a software release, plus any known bugs and bugs fixed in the current release.
research proposal A written request to research a problem in exchange for money or other resources.
rule A line that divides cells within a table or forms a border on the outside of a table.
Ill .
296 Glossary
run-on sentence A sentence that is longer than it should be. Alternatively, a sentence that the writer should divide into two or three separate sentences.
sans-serif font A font in which none of the characters are rendered with tiny little notches (serifs) at the endpoints. Sans-serif fonts are more readable than serif fonts in online documents.
screenshot A digital picture of an image that appears on a computer monitor. Software documentation for end users, installers, and system administrators often features screenshots.
secondary page Any Web page in a Web site other than the home page.
serif font A font in which all or most of the characters are rendered with tiny little notches (serifs) at the endpoints. In hard-copy documents, serif fonts are more readable than sans-serif fonts.
SGML Acronym for Standard Generalized Markup Language. HTML is a subset of SGML. Both are tagging languages, but SGML parsers are much stricter than browsers.
shading In tables, a gray or colored background on individual cells or on rows. Many tables use alternate-row shading in which every other row is shaded and the alternate row is unshaded.
sidebar A block of text and/or graphics displayed in a shaded background that contains an interesting digression off the main topic.
significance statement A one- or two-page explanation of why proposed research is important or relevant.
static content Information within a Web site that looks the same to every visitor on every visit. Compare to dynamic content.
stet An editor's comment that means "ignore my comments." An editor who writes some corrections in the margin of a book and then changes his mind would write stet next to his corrections.
structured documentation A guide in which the document consists of a set of chunks.
time-series graphs A two-dimensional graph in which the x-axis represents the passage of time.
Glossary 297
title The name of a document. In addition, a title is also a brief description of a table, typically prefaced by a number (for example, Table 3-1 Characteristics of Common Shade Trees). By custom, a table title appears just above each table. Compare to caption.
TOC Abbreviation for table of contents.
tone The emotional character of a document. Most technical documents have a serious, business like tone, although science writing for lay audiences often has a lighter, friendlier tone. Some modern consumer-product manuals even present a slightly flip or sarcastic tone.
transition A word or phrase that helps a reader move smoothly to the next sentence. Popular transitions in technical writing include however, for example, and therefore. When used, transitions are usually the first word or phrase in a sentence. Compare to conjunction.
tutorial A manual aimed at getting a neophyte started on a new topic.
variable-width font A font in which different characters occupy different amounts of horizontal space. Compare to fixed-width font.
Web page The information displayed at a specific URL. A collection of Web pages constitutes a Web site.
Web site An organized collection of Web pages, typically focused on providing information about a discrete topic or to serve a distinct audience.
white space A section of a hard copy document that does not contain any ink, or a section of a Web page that is rendered in the background color and pattern of that Web page.
298 Glossary
BIBLIOGRAPHY
• Aired, G., C. Brusaw, and W. Oliu. 2000. Handbook of Technical Writing: 6th ed. Boston, MA: Bedford/St. Martin's.
• Chicago Editorial Staff. 2003. Chicago Manual of Style: 15th ed. Chicago: University of Chicago Press.
• Friedlan, A. and C. Folt. 2000. Writing Successful Science Proposals. New York City: Yale University Press.
• Harlow, William M. 1957. Trees of the Eastern and Central United States and Canada. Toronto: General Publishing Company. This book served as source for the sample tables in Chapter 8.
• Kernighan, B. and D. Richie. 1988. The C Programming Language: 2nd ed. Upper Saddle River, N): Prentice-Hall PTR.
• National Science Foundation. 2004. Grant Proposal Guide. Arlington, VA: July.
• Nielsen, J. 2000. Designing Web Usability. Indianapolis: New Riders Publishing.
• Nielsen, ). and M. Tahir. 2002. Homepage Usability. Indianapolis: New Riders Publishing.
• Perelman, L, J. Paradis, and E. Barrett. 1998. The Mayfield Handbook of Technical & Scientific Writing. Mountain View, CA: Mayfield Publishing Company.
• Rich, S. and D. Gumpert. 1985. Business Plans That Win $$$. New York City: Harper and Row.
• Strunk, W., E. B. White, and R. Angell. 2000. The Elements of Style: 4th ed. Needham, MA: Pearson.
• Tarutz, Judith. 1992. Technical Editing. Reading, MA: Addison-Wesley.
• Tufte, Edward. 2001. The Visual Display of Quantitative Information. Cheshire, CT: Graphics Press.
• Tufte, Edward. 1997. Visual Explanations. Cheshire, CT: Graphics Press.
ibhography 299
Web Sites
• Purdue University. Department of Horticulture and Landscape Architecture. (www.hort.purdue.edu/hort).
• Riofrio, Marianne. Ohio State University Extension Fact Sheet. Fertilizing Vegetable Garden Soils, (ohioline.ag.ohio-state.edu).
II
300 Glossary
Symbols
:), 254
abbreviations, punctuation in, 287 above (word usage), 69 abstracts, 187
definition of, 291
in lab reports, 216
research proposals, 191 Acrobat Distiller, 177 Acrobat Reader, 176, 177 acronyms, 33
consistency, 33
expanding, 33
for nonnative speakers, 14
punctuation in, 287 active voice, 46
definition of, 291
lab reports, 47
strengths, 47 ADHD example, 216 adjectives, 36
in business proposals, 203 administration manuals
screenshots, 93 Adobe, 177 advanced topics, 138 adverbs, 36
in business proposals, 203 affect (word usage), 42 air pressure example, 114 algebraic formulas
explanations of, 112
aligning
graphics, 108
text in graphics, 97 alternate explanations, 120 anecdotes in footnotes, 123 Arial font, 273
Websites, 167 arrows, 97
as pointers, 104
focus, 106 articles in magazines, 196 assembly in high-level technical specs, 209 attention span
of Web site visitors, 166
PowerPoint presentations, 234, 243
winning it, 5 audience, 9
agitated, 17
appropriateness, 4
becoming, 19
book proposals, 195, 196, 197
breadth, 12
business plans, 198
college freshmen, 112
defining in a home page, 164
defining in a preface, 150
definition of, 291
doc spec example, 23
documentation project plans, 25
educational level, 10
emotional state, 17
empathy for, 19
engaging, 190, 227
examples, 114
experience, 11
expertise, 11
for this book, 20
Index 301
:
formula-based rules, 112 gaining empathy for, 19 getting attention of, 5 giving directions, 68 glossaries, 151
high-level technical specs, 206 market research data, 9 medium and message, 18 motivation of, 17 older, 278 peers, 238
question-and-answer format, 118 research proposals, 190 summary of, 20 superiors, 238 tone in Web sites, 167 visualization, 9 Website, 162 auditory learners, 242
B
back matter, 24 background colors
in PowerPoint presentations, 235
in Websites, 105 background information
in business proposals, 204
in tutorials, 136 bar charts
in business proposals, 205
PowerPoint presentations, 239 baseball terms and native culture, 15 becoming the audience, 19 before-and-after graphics, 89 beginner's mind and tutorials, 136 below (word usage), 69 BentonGothic font, 273 beta tests
documentation, 268
online help, 144 biographies, 185
examples, 186
research proposals, 191 block diagrams, 97
definition of, 291
white space example, 107 body language, 245
bold, 279
in graphics, 97 Book of Lists, The, 63 book proposals, 181, 195
audience, 196
contents, 196
example marketing section, 197
preproposals, 182
strategy, 195 boring writing, 5 breadth
audience, 12 breathing to relax, 246 brevity
online help, 143
secondary pages, 174 British readers and baseball, 15 browsers, default fonts, 167 budgets in research proposals, 191 bugs
in release notes, 147, 148
tracking, 266 bullet symbols, 64
definition of, 291 bulleted lists, 64
capitals, 71
definition of, 291
elements in, 65
in cookbook-style manuals, 134
introducing, 69
length of elements, 66
number of elements in, 64
online help, 144
parallel, 70
periods, 71
PowerPoint presentations, 236
second-level, 236
vs. embedded lists, 50
vs. numbered lists, 63 business plans, 181, 198
audience, 198
bios of consultants, 186
contents, 199
definition of, 291
marketing, 199
vs. business proposals, 202 business proposals, 201, 202
analysis, 203
definition of, 291
302 Index
example, 204, 205
marketing, 203
summary, 213
vs. business plans, 202 by comparison (transition), 56 by contrast (transition), 56
callouts, 90
definition of, 292
font height, 277
fonts, 275 can (word usage), 41 capital letters
in list elements, 71 captions
alignment of graphics, 108
definition of, 292
editing, 263, 269
tables, 83 cascading style sheets (see CSS) cells
amount of text, 80
units of measure, 75 centering
graphics, 108 CERN, 181
Chicago Manual of Style, 283 Chinese language, 13 Chinese restaurants metaphor, 49 choppy sentences, 51 chunks, 138
chunks, definition of, 292 citations in lab reports, 225 clarity, 4
in business plans, 198
in editorial comments, 261, 269
in internal planning documents, 201
in research proposals, 190
in speaking, 243 cliches, 40
click here hyperlinks, 172 client-server architecture example, 115 clip art in PowerPoint presentations, 239 clutter in layout, 107 colons, 288 color
block diagrams, 97
contrasting, 94
discontinuities, 105
hyperlinks, 173
PowerPoint presentations, 235
Websites, 167 color blindness, 95, 96
definition of, 292 column headers
in tables, 74 commands (see imperative verbs) commas, 284
parenthetical clauses, 52
that vs. which, 41 comparing technical writing to engineering,
8 components list
high-level technical specs, 207
low-level technical specs, 211 conceptual entries in indexes, 158 concise
example of, 5
FAQs, 179
phrases, 40
secondary pages, 174
sentences, 49
writing, 4 conclusions, 6
lab reports, 224
PowerPoint presentations, 228 conjunctions
definition of, 292
semicolons, 286
starting a sentence with, 57
vs. transitions, 57 consistency
footers, 263
graphics, 97, 98
headers, 263
labels, 127
of terminology, 99
of word usage, 33
reference pages, 140 content management software, 163 context-sensitive help, 143
definition of, 292 contingency plans, 188 contrast in color or shading, 105 cookbook style manuals, 134
Index 303
definition of, 292
example of, 135 copy edit, summary of, 269 copy editors, 259, 263
definition of, 292 Courier-New fonts, 274 cover letters, 184
definition of, 292
research proposals, 191 CPT, 216 criticism, 241, 269
e-mail messages, 255 cross-cultural examples, 16 cross-references, 140 CSS, 278
definition of, 292 cultural differences, 15, 16
e-mail, 252 cultural references, 15 cummings, e.e., 253
Danish language, 13 dashes, 285
parenthetical clauses, 52 data analysis in research proposals, 194 dates, in different countries, 16 defects in documentation, 266 definitions in glossaries, 151 descriptions
examples in, 114
of geometric figures, 127
precise, 126 design of research proposals, 194 design specs, 210
definition of, 292 developmental editor
definition of, 292 developmental editors, 259 diabetics example, 165 diagnostic information, 140 dialog in question-and-answer format, 118 dictionary-style documentation, 140 digital photography, 100
enhancing with line art, 101
establishing shot, 102 digressions, 124
footnotes, 123
online help, 144
sidebars, 122
within a sentence, 52 directions, giving, 68 discontinuities, 105 Discussion section of lab reports, 223 doc project plans
definition of, 292 doc specs
definition of, 293
example, 23
how to write, 22
issues list, 24
outline example, 24
purpose of, 21
reviewers list, 24
summary of, 28 documentation
beta tests, 268
conflicts, 267
cost of screenshots, 94
for programmers, 116
guides, 138, 139
pace, 122
question-and-answer format, 118
reference manuals, 140
schedules, 267
sets, 25
structured, 138 documentation planning, 21—28 documentation project plans
example of, 26
how to write, 25
summary of, 28 documentation specifications (see doc specs) documents
legal, 60
optimum number, 25 drop-dead-date in cover letters, 184 dull writing, 5 dynamic content, 163
definition of, 293
e.e. cummings, 253 editing, 259-269
304 Index
a superior's work, 262
copy editor, 263
diplomacy, 262
distributing, 263
effective, 260
e-mail messages, 252
hardcopy, 265
online, 265
relationship with writer, 261, 262
relationship with writers, 260
schedules, 267
summary, 269
time allocated, 267
tracking bugs, 266
your own document, 264 educational level
of audience, 10
of this book, 20 effect (word usage), 42 elements
definition of, 293
in bulleted lists, 65
in numbered lists, 67
length of, 66
parallel, 70
periods, 71 elevator speeches, 182
definition of, 293 em dashes, 285 e-mail messages, 249—256
cowardice, 254
debates in, 267
editing, 252
miscommunications, 255
Pickford Paradox, 249
problems with, 250
summary, 256
vs. formal documents, 251
vs. telephone conversations, 254
wars, 147 embedded labels, 91
definition of, 293 embedded lists, 50, 64
commas in, 284 emergencies, in index, 17 emoticons, 254 emotional state
e-mail messages, 256
of audience, 17
empathy with readers, 19, 138 encyclopedic documentation, 140 en-dashes, 285 endnotes, 123
definition of, 293 engaging audiences, 4, 5
pace, 122
PowerPoint presentations, 227, 234, 243 engineering
audience analysis of product, 144
compared with technical writing, 8
context-sensitive help systems, 143
cost of inventions, 49
critical analysis of writing, 45
documentation process, 266
editing process, 264
e-mail blasts, 255
management, 202, 238
plans for teams, 212
role of documentation plans, 21
specs, 209 engineers
audience for this book, xvii
biographies, 186
block diagrams, 97
bureaucracy, 252
business proposals, 202
commenting code, 140
Danish and Swedish, 13
editing, 259
e-mail messages, 251
fluff, 45
in management, 32
jargon, 32
low-level technical specs, 210
Pickford Paradox, 249
planning documents, 201
presenting revolutionary ideas, 189
proposals, 181
resistance to marketing, 36
sensitivity, 255
specs, 201
success and failure, 7
wardrobe, 245
writing level, 3 English as a pervasive technical language, 13 English as a second language, 13, 47
e-mail messages, 256
Index 305
equipment in lab reports, 219
Ernest Hemingway, and readability, 50
error codes, 17
in reference pages, 140 establishing shot, 102, 103 European Organization for Nuclear Research, 181 European readers and English, 13 examples, 114
abstract in lab reports, 216
abstract in proposals, 187
active voice, 46
air pressure, 114
beyond the obvious, 125
biographies, 186
bones in little finger, 90
book proposals, 197
boring, 5
business proposals, 204
client-server architecture, 115
color to grayscale, 125
Conclusion section of lab reports, 224
contingency plans, 188
cookbook-style manuals, 135
cover letter, 184
design and methods of research proposals, 194
digestive system, 91
digital photography, 101
Discussion section of lab reports, 223
doc specs, 23
documentation project plans, 26
DOS and UNIX commands, 78
electric force, 16
electron microscope, 150
elevator speeches, 182
e-mail messages, 250, 252
engaging, 5
Experimental Procedure in lab reports, 220
firewall, 119
for color blindness, 96
for this book, 20
gas pressure, 114
glossary, 152
graphics in PowerPoint, 239
gravitational force, 112, 113
guides, 139
Hello World, 116
high-level technical specs, 208
hot air and cold air, 5
hurricanes, 194
hyperlinks in body text, 172
in glossaries, 151
in reference pages, 140
introduction in lab reports, 218
it and they, 39
jargon and audience, 11
juggling, 101, 102
length of, 138
low-level technical specs, 211
Materials section of lab report, 219
metaphors, 115
mysteries in Web sites, 166
native culture, 15, 16
navigators in Web sites, 170
online help, 145, 146
passive voice, 48
PowerPoint lists, 236
PowerPoint presentations, 233
precision descriptions, 127
preface, 150
programming documentation, 116
question-and-answer format, 119
reference pages, 141
release notes, 148
research proposal objectives, 193
Results section in lab reports, 222
revolutionary proposals, 189
sans-serif fonts, 273
serif fonts, 273
significance statements, 192
table of contents, 153, 154
title of Web sites, 165
to explain rules, 112
tutorials, 137
white space, 108
you, 38 exceptions to rules, 112
example of, 113 exclamation points, 287 Experimental Procedure section in lab reports, 220 explanations, 112
alternate, 120
precise, 126 eyes as pointers, 104, 106
306 Index
face mask example, 142 failure
in cookbook style manuals, 134
in proposals, 1X8 familiarity of topic, 11 FAQs, 178
definition of, 293
vs. question-and-answer format, 118 fear of speaking, 246 feedback on documentation, 268 Fenster, 197 fiction
audience motivation, 17
conjunctions, 57
Henry James, 52
linear access, 18
metaphors, 115
reputation of author, 196
vs. technical writing, 3
word usage, 10 figures
(sec also graphics)
colons, 288
editing, 263 final doc specs, 22 firewall example, 119 fixed-width fonts, 274 fluffy phrases, 40 focus, 104
discontinuities, 105
on page, 106 focused audience, 12 following (word usage), 69 fonts, 271-282
callouts, 277
captions, 277
Courier New, 274
default, 273
definition of, 293
example of online help, 146
fixed-width, 274
foreign phrases, 279
hard copy documents, 275
headers, 277
height of, 277
in graphics, 97
in HTML, 176
in PDF, 176
instead of quotation marks, 290
italics, 279
lists, 277
Lucida Console, 274
paragraphs, 277
points, 277
PostScript, 281
PowerPoint presentations, 235
sans-serif, 272
screen resolution, 278
serif, 273
summary, 282
tables, 277
titles, 279
True-Type vs. PostScript, 281
Type 1, 281
variable width, 274
Web pages, 278
Websites, 167
weight of, 272, 273 footers
editing, 263
fonts, 275 footnotes, 123
definition of, 293
online help, 144 for example (transition), 56 foreign phrases, fonts, 279 formulas
explaining, 112
of technical writing, 8
readability, 50 frequently asked questions (see FAQs) Freud, Sigmund, 123 front matter, 24 function names, 116 functional specs (see high-level technical specs)
Caramond font, 273 general help, 143 generic verbs, 34 geometric descriptions, 127 glossaries, 151
example of, 152
Index 307
jargon, 32 Goldberg, Isaac
quote, 4 golden rule of indexing, 155 Goldman, William, 123 grammar
and native language, 13
politically correct, 37 grammatically parallel {see parallelism) grand finale, 244 graphics, 85-109
alignment on page, 108
before and after, 89
block diagrams, 97
clutter, 88, 107
consistency, 98
digital photography, 100
establishing shot, 102
FAQs, 179
geometric descriptions, 126
gray, 96
homepage, 166
in lab reports, 220
introducing, 99
labels, 90, 91, 99
layout, 104
online, 88
orienting readers, 92
photography and line art, 101
pointers, 104
PowerPoint presentations, 239, 240
summary, 109
telling a story, 142
three-dimensional, 98
white space, 107 graphs
detail in, 88
time-series, 86, 87 gravitational force example, 112, 113 grayscale, 96 guides, 138
definition of, 294
H
happen (word usage), 34 hard-copy documents
fonts, 275, 276
PowerPoint presentations, 240
vs. Web sites, 161 he (word usage), 37 headers
definition of, 294
editing, 263
fonts, 275, 277
in tables, 74
numbering, 60
table of contents, 153, 154 height of Web pages, 174 Hello World examples, 116
definition, 294 help systems (see online help) helping the reader, 4 Hemingway, Ernest, 50 hierarchies
bulleted lists, 65
headers, 60 high-level technical specs, 201, 206
analysis, 207
definition of, 294
example, 208
summary, 213 highlighting in screenshots, 94 home pages, 164
audience definition, 164
definition of, 294
engaging, 166
stating purpose of, 164
summary, 180
tone, 167 honesty
biographies, 185
hyperlinks, 172
lab reports, 221 horizontal scrolling, 174 HTML
<TITLE>, 164
definition of, 294
online help, 143
relationship to SGML, 280
sample of a guide, 139
vs. PDF, 176, 177 humor
in FAQs, 179
in PowerPoint presentations, 230
308 Index
in prefaces, 149 hurricane examples, 194
glossary, 152
research proposals, 193 hyperlinks, IX
color, 173
glossaries, 151
in body text of Web sites, 172
in FAQs, 179
in navigators, 170
in online help, 144
in reference pages, 140
right number of, 173
target windows, 173 hypotheses, 193
Discussion section of lab reports, 223
in lab reports, 216
in research proposals, 193
ideas per sentence, 51 ideas, revolutionary, 189 illustrations {see graphics) imperative verbs, 67
definition of, 294 in other words (transition), 56, 120 indexing, 155
conceptual entries, 158
editing, 269
entries for emergencies, 17
examples, 156
length, 155
permuting terms, 157
precise entries, 156 information density, 122
Web pages, 167 ingredients in cookbook-style manuals, 134 inoculation, 11, 189
business proposals, 203 installation manual screenshots, 93 internal planning documents, 201—213 Internet, 161
distributing documents on, 176
random access, 161
search boxes, 171 introducing
colons, 288
graphics, 99
lists, 69
Websites, 164 introduction of
document, 6
graphics, 99, 288
lab reports, 217, 218
lists, 60, 69, 288
new terms, 33, 118
paragraphs, 55, 58
PowerPoint presentations, 228
proposals, 184
research proposals, 194
tables, 288
topics, 136
Websites, 175
yourself, 182 it's (word usage), 42 italics, 279
in graphics, 97 its (word usage), 42
Japanese culture
baseball, 15
personal checking accounts, 16 jargon, 32
audience experience, 11
definition of, 294
e-mail messages, 256
Websites, 167 javadoc, 140 jokes
in footnotes, 123
in PowerPoint presentations, 230 juggling examples, 101, 102, 103
K
Kernighan and Ritchie, 116
key principles of technical writing, 4
King Kong social climber business proposal, 204 high-level technical spec, 208 low-level technical spec, 211
King, Stephen, 128
Index 309
%
lab reports, 215-226
abstracts, 216
citations, 225
Conclusion section, 224
Discussion section, 223
equipment list, 219
Experimental Procedure section, 220
introduction, 217
materials section, 219
passive voice, 47
References section, 225
Results section, 221, 222
sections in, 215
summaries of, 226
tense, 35 labels in graphics, 90, 91, 99
consistency, 127 language, native, 13 lay audience
explaining rules, 112
tables, 73
using jargon, 32
Websites, 167 layout, 104
definition of, 294
eyes on page, 106
Web pages, 168 learning styles, 242 legal documents, 18, 60 length
of books, 23
of documents, 25
of elements in numbered lists, 67
of paragraphs, 58
of PowerPoint presentations, 228
of sentences, 49 levels of sections, 60 line art, 101 lists, 63-72
bulleted, 64
citations, 225
colons to introduce, 288
commas in, 284
directions, 68
embedded, 50
fonts, 275
introducing, 69
length of elements, 66
numbered, 67
of equipment in lab reports, 219
parallel, 70
periods in, 71
PowerPoint presentations, 236
section headers, 60
summaries of, 72
to break up blocks of text, 122
types of, 63 literary editing, 269 literary editors, 259 long sentences, 49
causes of, 50
reducing, 51 low-level technical specs, 201, 210
definition of, 295
example, 211
summary, 213 Lucida Console font, 274 lying in a biography, 185
M
Macintosh fonts, 281 magazine articles, 196 males and color blindness, 95 managers
learning styles, 242
motivation, 202 manuals, 133-159
definition of, 295
guides, 138
in documentation project plans, 26
indexes of, 155
motivation to read, 17
nonverbal, 142
reference, 140
structured documentation, 138
summary of, 159
tutorial example, 137
tutorials, 136
vs. online help, 143 maps
gray, 96
in tourist areas, 92 market
defining in proposal, 187
310 Index
marketing
engineers' dislike of, 36
in book proposals, 197
in business plans, 198, 199
in business proposals, 203, 204
in high-level technical specs, 207
in PowerPoint presentations, 232
materials in lab reports, 219
may (word usage), 41
McNealy, Scott quote, 227
media
in documentation project plans, 27 plan, 25
medium and the message, 18
men and color blindness, 95
menus, documenting, 145
metaphors, 115
native culture, 15
methods in research proposals, 194
microscopy example, 150
miscommunications in e-mail, 255
misunderstandings and language, 13
monospaced fonts, 274
mood of audience, 121
motivation of audience, 17
movies as cross-cultural examples, 16
multimedia, 175
musical punctuation, 283
mysteries
PowerPoint presentations, 233 Websites, 166
N
National Science Foundation, 181 native culture, 15
dates, 16
examples, 16
for this book, 20 native language, 13
e-mail messages, 256
for this book, 20
simple words, 14 navigators in Web sites, 170
two-level, 171 nevertheless (transition), 56
New Jersey, 271 newspaper layout, 168 non-goals in doc specs, 23 non-native speakers, 13 nonparallel (see parallelism) nonverbal manuals, 142
definition of, 295 nouns versus adjectives, 36 NSF, 191 numbered lists, 67
capitals, 71
definition of, 295
directions, 68
in citations, 225
in cookbook style manuals, 134
introducing, 69
online help, 144
parallel, 70
periods, 71
vs. bulleted lists, 63
vs. embedded lists, 50 numbering section headers, 60
objectives in research proposals, 193
occur (word usage), 34
offensive photographs, 16
okay (word usage), 15
online editing, 265
online help, 143
best practices, 144
categories, 143
definition of, 295
examples, 145, 146 opening chapter of a book, 6 ordinal numbers in directions, 68
organizing writing, 6 outline in doc specs, 24
pace, 122
definition of, 295
of speaking, 243
PowerPoint presentations, 234 page counts, 25
Index 311
in list elements, 71 permuting index entries, 157 photographs
and line art, 101
establishing shot, 102
offending, 16
telling a story, 142
Websites, 167 picas, 296
Pickford Paradox, 249 pictures (see graphics) pie charts in business proposals, 205 planning, 201—213
documentation projects, 21—28
for failure, 188
media, 25
Websites, 162 pointers, 104
definition of, 296
eyes, 106 points, 277
definition of, 296 politically correct grammar, 37 pop-up graphic detail, 88 positive reinforcement, 261, 269 PostScript fonts, 281 PowerPoint, 296 PowerPoint presentations, 227—247
attention span, 243
background images, 235
body language, 245
body slides, 234
color, 235
fear of speaking, 246
final slide, 241
fonts, 235
grand finale, 244
graphics, 239, 240
interruptions, 229
introductions, 233
learning styles, 242
lists, 236
marketing speak, 232
mystery style, 233
number of slides, 229
opening slides, 231
organizing, 228
pace, 234
312 Index
pre-show, 244
printing, 240
question-and-answer sessions, 241
relaxation techniques, 246
speaking, 243, 245
speech, 244
starting, 229, 230
summary of, 247
to superiors, 238
what to wear, 243 practicing speaking, 246 preceding (word usage), 69 precision
index entries, 155 precision descriptions, 126 prefaces, 149
example, 150 preliminary doc specs, 22 preproposal
definition of, 296 preproposals, 182 present tense, 35 pre-show, 244
primary keys vs. table columns, 77 Princess Bride, The, 123 principles of technical writing, 4 principles, explaining, 112 printing
HTMLvs.PDF, 176
PowerPoint presentations, 240 professional secrets, 111 — 129
summary of, 129 programming documentation, 116, 117
quotes, 290 project description in proposals, 191 project plans, 25
(see also documentation project plans pronouns, 37, 38, 39 proposal review committees, 190 proposals, 181-200
abstracts, 187
biographies, 185
books, 195
business, 202
business (set' business proposals)
business plans, 198
commonalities, 181
contingency plans, 188
convincing reviewers, 189
cover letters, 184
definition of, 296
elevator speeches, 182
importance of, 181
inoculating against skepticism, 189
preproposals, 182
research (see research proposals)
revolutionary ideas, 189
summary, 200
templates, 183
within your company, 202 public speaking, 241, 243
crippling fear of, 246 publishers, 195 punctuation, 283-290
colons, 288
commas, 284
dashes, 285
emoticons, 254
hyphens, 285
periods, 287
quotation marks, 289
semicolons, 286
QA (see quality assurance)
Q-and-A format (see Question-and-Answer
format) quality assurance
beta-tests, 268
documentation, 267 Question-and-Answer format, 118
definition of, 296
example of, 119 Question-and-Answer sessions, 241
PowerPoint presentations, 228 questions in FAQs, 178 quotation marks, 289
R2D2, 16
random access of information, 18
readability quotients, 50
definition of, 296 readers (see audience)
Index 313
WM,,
reference manuals, 140
definition of, 296
example, 141
motivation to read, 17 References section of lab reports, 225 release notes, 147
definition of, 296
example of, 148
in documentation project plans, 26 repetition, 6, 50 reports, status, 253 research proposals, 181, 190, 193
audience, 190
contents of, 191
contingency plans, 188
data analysis, 194
design and methods, 194
methods, 194
methods and materials, 194
objectives, 193
overview of experiment, 194
significance statements, 192
strategy, 190 Research section of lab reports, 224 resolution of different media, 18 results in research proposals, 194 Results section in lab reports, 221 reviewing documents, 259 revolutionary ideas, 189 rhetorical questions, 114 romantic-comedy style of overviews, 231 rows of a table, sorting, 78 rules in tables, 81
alternative, 82
definition of, 296 rules, explanations of, 112 run-on sentences, 45, 51
definition of, 297
safety equipment, 142 safety issues and tone, 121 sans-serif fonts, 272
definition of, 297
examples of, 273
hard-copy documents, 275
height of, 277
soft-copy documents, 276
Web sites, 167 schedules
doc specs, 22
documentation project plans, 25
in documentation projects, 267
in high-level technical specs, 209 schematics, in documentation project plan,
27 science, compared with technical writing, 8 scientific writing
creativity, 5
value of, 3 scientists
aiming documents at, 36
audience for this book, xvii
common language, 13
editing, 259
fashion sense, 245
mysteries, 233
Q-and-A format, 118
research proposals, 190
revolutionary proposals, 189
technical reviews, 259
writing and, 8
writing lab reports, 215 screen resolution and fonts, 278 screenshots, 93
cost of, 94
definition of, 297
highlighting, 94 scrolling
HTMLvs.PDF, 176 search boxes in Web sites, 171 search engines, 162 secondary pages, 162
definition of, 297
summary, 180 second-level index entries, 157 sections, 55, 60, 153
numbering headers, 60
summary of, 61 self-doubt, xx, 128 self-editing, 128 semicolons, 286
sentence fragments in bulleted lists, 65 sentence variety, 35
passive voice, 48 sentences, 45—53
314 Index
active voice, 46
choppy, 51
deleting unnecessary, 53
digressions, 52
long, 50
number of words in, 50
opening a section, 60
opening in a paragraph, 6
passive voice, 46
per paragraph, 58
repetition, 50
run-on, 45, 51
semicolons, 286
short vs. long, 49
starting with conjunction, 57
strong, 47
summary of, 53
topic, 55
transitions, 56
variety of, 48 serif fonts, 272
definition of, 297
examples of, 273
hard-copy documents, 275
height of, 277
soft-copy documents, 276 serifs, 272 SGML, 280
definition of, 297 shading
discontinuities, 105
in tables, 82 she (word usage), 37 short sentences, 49 sidebars, 122 signal-to-noise ratio
fonts, 275, 276
readability, 50
sentences, 45 significance statements, 192
definition of, 297 silent films, 249 size of fonts, 277 skeptical readers, 11 slang
e-mail messages, 256
native culture, 15 slides (see PowerPoint presentations) smiley faces, 254
soccer in examples, 15 soft-copy documents
editing, 265
fonts, 276, 278 software documentation
quotation marks, 290
release notes, 148 software manuals
cookbook example, 135
example of a guide, 139
guide example, 139
nonverbal treatment, 142
tutorial example, 137 sorting rows in a table, 78 speaking, 243
fear of, 246 specifications {see specs) specs, 201-213
design, 210
functional, 206
high-level technical, 206
low-level technical, 210 speech, 243
lessons from professional entertainers, 244
overcoming fear, 246
telling jokes, 230
transitions, 57 spell checkers, 263, 264, 266
context problems, 269 split infinitives, 13 Spring Into Series, 138 stage freight, 241
Standard General Markup Language, 280 stapler and ruler example, 113 starting a project, 128 static content in a Web site, 163
definition of, 297 stet, 297
straight quotes, 290 strong verbs, 34 structured documentation, 138
relation to reference manuals, 140 subheads within Web pages, 175 subjects
active vs. passive, 46
missing, 47
obscuring, 48 sublists, 65
:■ :
sugar, spoonful of, 261 summaries
business proposals, 213
doc specs, 28
documentation project plans, 28
editing, 269
e-mail messages, 256
fonts, 282
graphics, 109
high-level technical specs, 213
home pages, 18(3
lab reports, 226
lists, 72
low-level technical specs, 213
manuals, 159
paragraphs, 61
PowerPoint presentations, 247
professional secrets, 129
proposals, 200
secondary pages, 180
sections, 61
sentences, 53
tables, 84
Websites, 180
words, 43 summarizing in technical writing, 6 Sun Microsystems, 227 support organizations and release notes, 147 Swedish language, 13 synopsis
business proposals, 204
high-level technical specs, 207, 208
low-level technical spec, 211
tables, 73-84
amount of text in cells, 80
audience reaction, 73
captions, 83
colons, 288
column headers, 74
editing, 263
font height, 277
fonts, 275
for variety, 122
introducing, 76
leftmost columns, 77
organizing, 77
parallel, 79
referring to, 76
rules in, 81
shading, 82
sorting, 78
summary of, 84
titles, 83
vs. primary keys, 77 tables of contents, 153
editing, 263, 269
entries for emergencies, 17
example, 154 target audience for this book, 20 teams of engineers, 212 technical editing, 259
see also editing
summary of, 269 technical editors, 259 technical overview in high-level business
specs, 207 technical writing
compared with engineering, 8
creativity, 5
formulas, 8
overview, 3—8
parts of speech, 36
practicing, 4
success and failure, 7
theorems, 4
topic sentences, 55
value of, 3
vs. fiction, 3
vs. painting, 4 technology overview
high-level technical specs, 208 technology overview in technical specs, 208 television
affect on reading, 161
vs. Web sites, 166 Tell 'em, 6
temperature graphs, 86, 87, 88 templates
proposals, 183
Web pages, 168
Websites, 169 tense, 35 terminology
316 Index
consistent, 99 testing
documentation, 268
jokes, 230
online help, 144
technical writing and engineering, 8 that (word usage), 41 that is (transition), 56, 120 theti (word usage), 67 theorems of technical writing, 4 there is (word usage), 34, 35 they (word usage), 37 thoughts per sentence, 51 three-dimensional graphics, 98 time allocation in PowerPoint presentations,
228, 229 time of day for presentations, 234 Times New Roman font, 273 time-series graphs, 86, 87
definition of, 297 tire example, 114 titles
of PowerPoint slides, 231
of tables, 83
of Web pages, 164 to be (word usage), 34 TOC, 298 tone, 121
definition of, 298
FAQs, 179
Websites, 167 topic sentences, 55 tourist maps, 92
tracking documentation bugs, 266 trademarks, 263 transistors, 32 transitions, 56, 57
between paragraphs, 59
definition of, 298
semicolons, 286
vs. conjunctions, 57 translating from English, 14 troubleshooting
cookbook-style manuals, 134
in reference pages, 140 troubleshooting manual, 27 True-Type fonts, 281 tutorials, 136
definition, 298 example of, 137 relation to guides, 138 Twain, Mark, xvii, 147 Type 1 fonts, 281 typography (5ft'fonts)
u
UK readers and baseball, 15 unfortunately (transition), 56 units of measurement in tables, 75
variable names, 116, 117 variable width fonts, 274 variety
changing pace, 122
PowerPoint presentations, 234
question-and-answer format, If VCs (see venture capitalists) venture capitalists, 181 verbs, 34
compared to adverbs, 36
simplicity of, 14
strong, 34
tense, 35
varying, 35 Verdana font, 273
Websites, 167 viruses and hyperlinks, 172 visual cues in layout, 104 visual learners, 242 visualizing audience, 9 vocabulary
non-native speakers, 14
w
wardrobe of engineers, 245 warranty cards, 24 weather glossary, 152 weather station doc spec, 23 Web pages
associating related, 174
Index 317
: ■;
318 Index