Technical Writing made easier

s the impression of speaking just
that little bit too loud. Using ‘do’ as in the introductory sentence of this paragraph as a verb by
itself is in order. But it does give a certain obnoxious quality of overassertiveness to your writing if
you do use it as an auxiliary verb when you definitely do not need to use it to say what you do want
to say. Now that does settle this point, does it not?
5.11 Time is on our side
Always try to keep the (grammatical) tense of technical documents in the present. Past tense ought
to be out of the question, as we generally are not concerned with past developments. The future
usually also is beyond our scope, as we do not yet know what future revisions of our program will
bring.
5.12 Consistency
Be consistent in the use of either British or US-english spelling. Never switch inside any given
document. Examples of difference in spelling between those two are:
British US
Colour Color
Co-operation Cooperation
Customisation Customization
Also, once you choose a given technical term to mean one thing, use it only in that one sense. Do
not redefine!
5.13 Editor's pet peeves
At some point in any writer's life comes the moment where his work is submitted to an editor. This
breed of person does have a lot of experience with language and the common weaknesses of the
technical writer. Over time it has become clear that the same mistakes are made again and again.
So, save them time and yourself humiliation by following the list below. It contains additional
material not covered above.
To make things easier, the list is organized by topic. The most important issues or the most
commonly misused terms are bolded. The words in this list are supposed to be spelled as printed
here, including capitalisation, hyphenation or lack thereof, and separated or not as given. Also note
that US-english is the reference here, as opposed to the other text9, as almost all technical writing is
published by American publishing houses.
5.13.1 Grammar and Logic
• allow vs enable: People allow; objects enable. Some editors are more stringent
about this rule than others. - Georgie allowed me to borrow his CD. The program
enabled me to create a stunning document. You might also consider to use let as
synonym for allow. - He let me borrow his CD.
• although vs while vs whereas: Use while only when describing the action of doing
two things simultaneously. Use although and whereas for contrast.
9 Now, that is my personal decision I choose to make as the author of this Tech Note.
© Bernhard Spuida, 2002 12
• Figures: The first reference to a figure should always be before it is presented.
Ensure that the spellingof terminology in figures is same as in the text. Captions
(please remember to include them) should be informative sentences. - bad caption:
The File Open dialog box. good caption: In the File Open dialog box we ... When
referenced in the text with a specific number, the term 'Figure' is always
capitalized.
• graphic (n): The noun form usually takes a singular verb. 
• graphics (adj): Use graphics as an adjective in relation to the field of graphic art or
graphic design - graphics file is ok.
• once vs after vs when: Use once for time references. Use after to show that an
event has already taken place. Use when to show actions or events that are
occurring simultaneously.
• over vs more than: Over denotes crossing a barrier or exceeding a limit. More than
qualifies a number. - She has worked more than 60 hours this week.
• preceding vs previous: Preceding means immediately before in time and place.
Previous means simply earlier, prior, or before, but not necessarily immediately
before. For example, if the current month is June, the preceding month is May;
previous months are January through April.
• since vs because: Use since for time references. Use because when explaining the
reasons why something happened.
• There is, There are/ Here is, Here are: Sentences starting with this construction
are usually more clear and less wordy if they're rewritten.
5.13.2 Spelling and Terminology
z above, below: Avoid this terminology when referring to figures or other references.
Instead, be specific (see Figure 24.2) or use preceding, following, next and so on.
See also preceding.
• backward, toward, forward (no "s" on any of these words)
• check box, check mark
• back up (v); backup (n)
• clip art
• Clipboard
• CompuServe
• Control Panel
• Ctrl key (spelled as it is on the keyboard)
• Ctrl+Alt+Delete vs Ctrl-Alt-Delete: On the PC, keystroke sequences are separated
by plus signs. In Mac texts, sequences are separated by hyphens. This however, is
subject to variation depending on the editor's preferences.
• desktop
© Bernhard Spuida, 2002 13
• disc vs disk: Use disc when referring to a CD or an optical; Use disk when
referring to a 3 1/2- or 5 1/4-inch disk. Never use diskette.
• double-click, right-click, left-click (always hyphenated as verb)
• drop-down (adj, n); drop down (v)
• email: no hyphen, no capitalization
• filename
• home page
• hotkey (one word): Make sure that hotkeys are marked in the chapters. Hotkeys are
indicated typographically.
• HTML: Hypertext Markup Language (notice that the "t" in Hypertext is lowercase)
• inline
• intranet is lowercase; Internet is uppercase
• ISP: Internet service provider (no need to make the "s" and the "p" uppercase)
• keyword
• log in/login vs log on/logon: Both forms are acceptable, but be consistent. As a
verb, log in or log on are two words. As an adjective, login and logon are one
word.
• Measurements
bps bit per second
GHz gigahertz
Hz hertz
KB kilobyte
Kb kilobit
Kbps kilobits per second
KHz kilohertz
MB megabyte
Mb megabit
Mbps megabits per second
MHz megahertz
ms millisecond
• As for Kilobytes, be consistent in using either decimal (1K=1000) or power of two
(1K=1024) notation. The former is to be preferred for physics, the later for
computer science contexts. This also holds true for higher powers (mega, giga,
tera, peta).
• menu bar
• multi, non, re, sub, and co prefixes: It's almost always safe to assume that you
© Bernhard Spuida, 2002 14
don't need to hyphenate these words. (For example, the correct spelling is
multicolumn, not multi-column.) A few exceptions to note are as follows:
 resort vs re-sort: Resort means a place of retreat; re-sort means to sort
again.
 recreate vs re-create: Recreate means to cut loose; to play. Re-create
means to create again.
 resent vs re-sent: Resent means to show displeasure or indignation
because of a feeling of being injured or offended. Re-sent means you sent
something again.
There are a few exceptions in British usage though, such as co-operation. Settle the
reference spelling context once and for all when you begin writing.
• Net - uppercase when referring to Internet, .NET or .net - all upper or lower case
when referring to the Microsoft technologies, be consistent with the choice for the
latter term.
• newsgroup
• offline, online
• offscreen, onscreen
• pathname
• Plug and Play
• PostScript
• pull-down menu
• ScanDisk
• scrollbar
• set up (v); setup (n, adj)
• Spacebar
• status bar
• Tables: Be specific when titling tables, and use sentence style capitalization (only
first word and any proper nouns are capitalized) for table heads. As with figures,
the word Table should be capitalized when a specific table is being mentioned
(Table 4.5), but lowercase when the reference is generic (The following table... ).
An ending period is no longer used after the table number in any series (Table 4.5
is correct; Table 4.5. is incorrect).
• taskbar
• terminology: Consistent use and capitalization of terminology is important. A
novice reader as well as a general tech editor won't always have the knowledge or
the software about which you write and thus won't always be able to catch
technical inconsistencies. 
• title bar
• ToolTip, ScreenTip
• TrueType font
© Bernhard Spuida, 2002 15
• UNIX
• up-to-date (always hyphenated)
• URL: uniform resource locator ("u" stands for uniform, not universal).
• Usenet
• username
• Web - is always uppercase)
• wizard: Use uppercase "w" when talking about specific wizard and lowercase "w"
when talking about generic
• worldwide (one word, unless referring to World Wide Web)
6 Recommended Reading
Of course no complete list of books on style can be given here. The selection must by necessity be a
personal one. So I will just list a few books I found useful for myself:
Strunck & White: ‘The Elements of Style’
‘The Chicago Style manual’
‘The King’s English’
Stephen King: ‘On Writing’ (Good ideas about writing in general, not technical. And a nice bit of
autobiography, too.)
Some books that are well written and will give some idea of what can be done:
Robert M. Pirsig, ‘Zen and the Art of Motorcycle Maintenance’ (An interesting book about
motorcycling, ,the human psyche, ‘quality’ and — a little — about technical writing, all
well written)
Douglas R. Hofstadter: ‘Gödel, Escher Bach – an Eternal Golden Braid’ (Some of the finest writing
ever on the concept of ‘Strange Loops’ which manages to get some rather technical points of
AI and programming across without being boring)
Donald Knuth: ‘The T
e
X book’ (One of the finest software manuals ever written. Even the more
arcane aspects of TeX are clearly explained in an entertaining way)
The VAX manuals, a.k.a. ‘The Orange Wall’ (Tons of paper, the best set of software documentation
ever. Much better than most man pages and galaxies ahead of PC-software documentation)
7 Online Resources
Some online translation and dictionary resources:
© Bernhard Spuida, 2002 16
As you will notice, some of these refer to issues specific to the German language. Even if you are
not a native speaker of German, these will illustrate some of the basic problems with nativisms. 
© Bernhard Spuida, 2002 17