Technical Notes, general Series

Technical Writing made easier

rev. 1.1, March 2002
by Bernhard Spuida, Error! Hyperlink reference not valid.
Senior Word Wrangler
Table o !ontents
1. Introduction........................................................................................................................2
2. Theory................................................................................................................................2
3. Readability.........................................................................................................................3
3.1 Well formed Sentences.......................................................................................................... 3
3.2 Overlong Sentences.............................................................................................................. 4
3.3 Short Sentences.................................................................................................................... 4
3.4 Recursion............................................................................................................................... 4
3. !hoice of Words....................................................................................................................
4. !om"rehensibility...............................................................................................................
4.1 #efinition................................................................................................................................ $
4.2 %ssum"tion&Theorem............................................................................................................. $
4.3 '("lanation&)roof................................................................................................................... $
4.2 !onclusion............................................................................................................................. $
. *atters of Style..................................................................................................................+
.1 Title........................................................................................................................................ +
.2 ,ig Words.............................................................................................................................. +
.3 It-s.......................................................................................................................................... .
.4 %n -a-...................................................................................................................................... .
. #o not use -don-t-................................................................................................................... .
.$ !an/ could/ etc....................................................................................................................... .
.0 1ativisms............................................................................................................................. 12
.+ 'go Tri"............................................................................................................................... 12
.. When to use -if-.................................................................................................................... 12
.12 This Sentence does overdo it............................................................................................. 12
.11 Time is on our side............................................................................................................. 11
.12 !onsistency....................................................................................................................... 11
.13 'ditor-s "et "eeves............................................................................................................. 11
.13.1 3rammar and 4ogic................................................................................................................... 11
.13.2 S"elling and Terminology........................................................................................................... 12
$ Recommended Reading...................................................................................................1
Bernhard Spuida, 2002 1
0 Online Resources..............................................................................................................1
Bernhard Spuida, 2002 1
1. "ntroduction
Technical writin re!uire" clarity of e#pre""ion and therefore "i$plicity of lanuae. Technical
writin i" intent on e#pre""in certain key concept" "o that the"e $ay %e under"tood a" ea"ily a"
po""i%ly %y the intended reader" & %e they prora$$er" or u"er". 'ritin in a clear, conci"e
$anner $ake" not only under"tandin the te#t ea"ier for the reader, it al"o $ake" your life a" a
writer of technical docu$entation ea"ier & e"pecially when you are not a native "peaker of Enli"h.
'hen talkin a%out alorith$", or "e!uence" of event" in a prora$, a%"olute clarity of writin i"
not only needed in the code di"cu""ed( %ut al"o in docu$entin thi" particular prora$ for our
fellow prora$$er" and u"er". 'e need to attain the "a$e level of clarity of e#pre""ion in %oth
ca"e", otherwi"e reader" will to turn to other prora$", which are $ore acce""i%le on the level of
under"tandin and therefore ea"ier to u"e or e#tend.
)n thi" "hort uide, we will cover "o$e of the %a"ic concept" that lead to ood *technical+ writin.
,ou will certainly di"cover $ore "uch rule" and concept" a" you practice the writin "kill" ained
out of thi" "et of note". -nd al"o, read! .ead a lot, and read varied writin, con"ciou" of the way"
lanuae i" u"ed in the te#t" you read. Have your own writin read and critici"ed %y friend" and
fellow profe""ional". /ay attention to the"e critici"$".
,ou will "ee that our colleaue", 0u"t like the co$puter" we prora$, re!uire a "pecific "ynta# to %e
adhered to if we want our in"truction" to %e under"tood. -nd a" in prora$", hu$an lanuae te#t
$ay %e "traihtforward or convoluted, leadin a" in prora$" to variation" in perfor$ance. So here
we o.
-" thi" i" intended to %e a 1work in prore""1, addition" will %e $ade whenever nece""ary. ) a$ al"o
alway" happy to receive "ue"tion" and feed%ack.
2. Theory
The under"tandin of written te#t depend" on three di"tinct co$ponent"2
3ei%ility
.eada%ility
4o$prehen"i%ility
The fir"t of the"e co$ponent" i" of no concern to u", a" it i" a re"pon"i%ility of the layouter" and
type"etter" puttin our writin into it" final for$.
The "econd of the"e we will deal with, a" it i" vital to havin the reader actually read our docu$ent,
hopefully in full.
-nd la"tly, the third co$ponent i" e""ential to en"ure that our reader will understand the purpo"e of
our writin.
Bernhard Spuida, 2002 2
The"e two co$ponent" will %e di"cu""ed in "eparate "ection", even thouh "o$e of the i""ue" rai"ed
$ay %e pertinent to %oth.
)n addition, we will al"o look at i""ue" of "tyle & "o$e of writin5" do5" and don5t" , a" even the
pro"e of technical writin doe" not have to %e e!uivalent to a %lunt a#e when it $iht %e an
in"tru$ent of preci"ion.
Should you, kind reader, have "ue"tion" for i$prove$ent to the"e pae", plea"e let $e know2
%ernhard6ic"harpcode.net
#. $eadability
The concept" of reada%ility and co$prehen"i%ility i$ply that the act of readin %eyond the phy"ical
act of "eein and decipherin character" and chunk" of te#t i" va"tly $ore co$ple#.
-" the ne#t "tep %eyond thi" 7raw5 level of input, we need to a""u$e a proce"" of tokeni"in, akin to
what a co$piler doe" with the "ource code of a iven prora$.
Thi" proce"" of tokeni"in i" what reada%ility i" concerned with. Thu", our writin will need to $eet
a nu$%er of re!uire$ent" to "ucce""fully pa"" thi" "tae2
1. The sentences must be well formed syntactically
2. The sentences must not exceed a certain length
3. The sentences should not be below a minimum length
4. Recursion must be kept to a minimum
5. The choice of words should ary
!f a technical text is unreadable in the reader"s eye# he will $uite probably assume that the product
described in this text also is of inferior $uality. %ode is a language# &ust as the language of the
documentation is. 'ot writing well in documentation implies faults in coding style.
Therefore, readability is an absolute requirement for documentation of successful products.
3.1 Well formed Sentences
By well for$ed "entence", we do not $erely $ean that the "entence" "hould confor$ to
ra$$atical rule" of the Enli"h lanuae, %ut al"o that they are clearly %uilt. 'e will now look at
"o$e neative" and di"cu"" "olution"2
This sentence no verb
8larin ra$$atical error" "uch a" o$ittin a vital co$ponent of the "entence & in thi" ca"e the
ver% & "hould %e avoided at all co"t. .ead out loud, whenever in dou%t. 9"ually, the"e $i"take"
occur in loner, $ore convoluted "entence". 4heck the"e twice when they cannot %e rewritten in
"plit:up for$.
Bernhard Spuida, 2002 2
This sentence does a verb have
;ever, ever try to tran"po"e a ra$$atical con"truct of your $other tonue into a literal Enli"h
e!uivalent & even $ore "o in ca"e" of collo!uiali"$", a" a%ove! )f you are a%le to tran"late a
"entence word %y word %ack into your $other tonue, you $o"t pro%a%ly $ade a "evere $i"take or
two in writin it. .ead te#t" %y native "peaker" of Enli"h. .ewrite your own te#t ne#t, and then
reread it.
In this case, we see that there is, as such, a larger than necessary number of commas.
/unctuation "hould %e kept to a $ini$u$. )t i" not nece""ary to put a co$$a wherever it look"
riht. They often are not. E"pecially clau"e" of the 7"o that5 type can do perfectly well without
co$$a". Thi" rule of cour"e al"o hold" for all other punctuation. -nd never, ever, try to tran"port
punctuation rule" fro$ your native tonue to the Enli"h you are writin.
<f cour"e, $any $ore ca"e" of "entence" not well for$ed $iht %e con"tructed, %ut !uite pro%a%ly
you will find enouh of the"e when lookin throuh variou" piece" of writin. -nd not only will
you find the"e in non:native writer" of Enli"h. Therefore, aain & read what other" wrote!
<f cour"e, $o"t of the further e#a$ple" of "ection = al"o are $alfor$ed in our wider "en"e.
3.2 Overlong Sentences
<ften we encounter "entence" which run on too lon. 9nder"tandin "uch "entence" i" e#tre$ely
difficult, a" "hort ter$ $e$ory ha" a very li$ited capacity. Si$ilar to the rule that telephone
nu$%er" $ay not have $ore than > diit" plu"?$inu" two, "entence" "hould not e#ceed a certain
lenth.
It is given as a rule, which however is not the only such rule you may encounter, that sentences
should not exceed a desirable length of ten to fifteen words, never should fall below seven words or
extend beyond the ultimate limit of tolerable length reached at twenty words, even though longer
sentences may be found in high literature, where even punctuation as it is used in this example to
facilitate reading is oft omitted in novel experimental ways.
Thi" of cour"e i" an e#a$ple that run" "o$ewhat loner than what you would e#pect to find in your
own writin. But read your own te#t" aain and you will !uite po""i%ly find one or two of the"e
a%o$ination", de"cri%in "ay, a co$ple# chain of event" and their handlin. - co$ple# train of
thouht can only %enefit fro$ %ein %roken down into "entence" of convenient lenth. Te$ptation
to ra$%le on in one lon "entence $ay %e reat. .e"i"t. ,our loic will %enefit. -l"o cut out
anythin not nece""ary to the i$$ediate cau"e at hand. To !uote Strunck and 'hite5" third rule2
Omit needless words.
Bernhard Spuida, 2002 2
3.3 Short Sentences
Short "entence" are ea"ily read, %ut tend to look %reathle"" and overly e#cited.
Sentences may be short. Then they are easy to read. And understand, too. But they look cheap. And
breathless. As well as leaving the reader restless.
;ot $uch need" to %e "aid here, a" the"e a%ove "entence" illu"trate the point to %e $ade. )f a thin i"
worth "ayin, it i" worth "ayin it well, not choppin lanuae to piece". Hu$an lanuae i" not a
.)S4 lanuae.
)n eneral, try to vary the lenth of "entence" in the li$it" iven in the neative of "u%"ection =.2
a%ove. )ntere"tin writin depend" on well do"ed variation" of lenth and choice of word" & for
e#a$ple" of the latter, "ee %elow.
3.4 Recursion
Sentence" often turn into a !ua"i:circular ca"e of recur"ion while readin the$ when the reference"
$ade in the "entence to the re"pective o%0ect" and "u%0ect" are left unclear %y u"in the "a$e
pronoun to de"cri%e the"e "u%0ect" and o%0ect".
It is not easy to understand it when it is unclear what is referenced by it! " it by now should be
clear what it is supposed to mean, isn!t it#
)n "uch a ca"e, replace one & prefera%ly the fir"t & in"tance of each "u%0ect?o%0ect referenced %y
7it5 with it" actual na$e. Thi" will $ake readin $uch ea"ier. .ecur"ion of thi" type often al"o i" an
indication of la@ine"" on the writer5" part, a" it hint" at an unwillinne"" to for$ulate a thouht
properly. Thi" however i" only a "hort ter$ "avin of effort, a" reader" pro%a%ly will contact the
author a"kin for clarification and thu" cau"in $ore unproductive work on the writer5" part than
nece""ary.
-nother for$ of recur"ion will take place in the reader5" $ind when he i" confronted with
convoluted "entence" containin in"ertion", ellip"e" and other rhetoric fiure". -ll of the"e will need
"o$e place on hi" 7"tack5 & and a reader5" "tack i" "hallow. 7/u"hin5 and 7poppin5 $ore than
three "tack level" u"ually end" in di"a"ter A for the $e""ae of your "entence!
The reader, that is, the intended recipient of our text, a hopefully clearly written and logically
structured document, will, if he is able to fully understand our prose, without difficulty come to a
safe assumption of what any given sentence, such as this a one, conveys, to him, the reader, by the
way of meaning.
The a%ove "entence i" ra$$atically correct, %ut will $o"t pro%a%ly provoke a 7"tack overflow5 in
our averae reader. Such convoluted
1
writin "hould %e avoided wherever po""i%le. Bu"t a" recur"ive
1 8o ahead, look up 7convoluted5 in a dictionary. ;ow. Co thi" a" well for any other word you $ay not know in thi"
or any other te#t.
Bernhard Spuida, 2002 2
code, te#t $ay %e 7flattened out5. Take a $on"ter "uch a" the one a%ove apart. Shorter "entence"
$ake ea"ier readin. )f thi" i" not po""i%le, try to keep related part" of the "entence" a" clo"e to each
other a" po""i%le.
3.5 Choice of Words
.eadin i" a proce"" that take" it" toll on the reader. Thi" ta"k "hould therefore %e $ade a" ea"y a"
po""i%le for hi$. Dakin readin an ea"ier ta"k, if not a plea"ure, can %e achieved %y varyin the
voca%ulary u"ed to de"cri%e the topic" at hand.
$sing the same words all over to describe the same things again and again is not pleasant even
more so when we can use different words to replace those same words we are using again and
again to describe the same thing in the same words.
Eor any iven word, at lea"t one "ynony$ will %e availa%le. Co not he"itate to u"e a the"auru". -l"o,
do not u"e the e#act "a$e phra"in aain and aain and aain, unle"" it i" intended to convey "o$e
arti"tic intention & thi" however i" al$o"t never the ca"e in technical writin. -nd2
Never use the same opening words in two or more subsequent sentences. Repetitive writing is
the enemy of all reader's interest.
%. !omprehensibility
)n the co$ple# proce"" of readin, the "tep followin the 7tokeni"ation5 of the te#t i" the actual
7par"in5 & under"tandin what the"e "y$%ol" and their relation" $ean. - clear "eparation of the"e
two "tep" however can not %e $ade.
- reat portion of co$prehen"i%ility i""ue" already wa" covered when we di"cu""ed recur"ion
a%ove.
Recursion is the enemy of understanding
(n understandable technical document always follows a logical structure. (ny topic discussed is
based on the preceding topics. !f a new concept is needed for the topic at hand# it needs to be
introduced before using it in dealing with this new topic. This holds true for any leel of detail of
the document at hand# down to indiidual sentences.
The basic steps are)
1. *efinition
2. (ssumption+Theorem
3. ,xplanation+-roof
4. %onclusion
.f course# the classic structure of /thesis, antithesis, synthesis" may be more appropriate for certain
Bernhard Spuida, 2002 2
topics# such as discussion of architectural decisions# but generally the aboe se$uence is exactly
what we need.
.n the /atomic" leel of a sentence# its logical structure is goerned by raw grammar. Therefore# a
good working knowledge of grammar is absolutely necessary for getting our ideas across to the
reader as we mean them to be.
4.1 Definition
)n thi" "e$ent of the docu$ent, all ter$" and concept" nece""ary for the followin "hould %e
defined. )n "o$e ca"e", reference to previou" $aterial in the docu$ent i" "ufficient. .eferrin to
later "ection" i" to %e avoided at all co"t. )f it "hould for "o$e rea"on %e nece""ary, the definition"
$ay %e placed in endnote" or a lo""ary at the end of the docu$ent. Thi" "hould %e clearly indicated
at the very %einnin of the docu$ent. Eootnote" are not intended for the purpo"e of definition".
They are a place for further e#planation" or $aterial of a 7non "e!uitur5 nature
2
.
4.2 Assumption!heorem
The ta"k of thi" "e$ent i" the pre"entation of the idea or concept thi" particular docu$ent or part of
a docu$ent i" "uppo"ed to deal with.
Dake a "i$ple and clear cut "tate$ent of where your aru$ent "tart" and what will %e the intended
outco$e. ;o why or how "hould %e iven here. The why "hould %e clear fro$ earlier portion" of the
docu$ent, the how i" the "u%0ect $atter of the ne#t "ection.
)n a u"er5" uide, thi" i" where an indication of the function to %e e#plained "hould %e iven.
4.3 "#pl$n$tion%roof
Thi" "e$ent of our docu$ent deal" with ivin 0u"tification for the idea put forth in the previou"
"ection. )t $ay %e of purely aru$entative
=
nature & "ay, defendin architectural deci"ion" & or
co$e clo"e to $athe$atical proof in "tyle. )n the ca"e of a prora$ i$ple$ented practically, thi" i"
the place for e#plainin the workin" of it "tep %y "tep. <r in the ca"e of a u"er5" uide, to e#plain
the interface and "e!uence of "tep" nece""ary for co$pletin a iven ta"k.
4.2 Conclusion
Eor the docu$ent to %e "ucce""ful, a conclu"ion $u"t %e iven, reiteratin the a%ove "tep" in a
"hortened for$. Thi" will reinforce the i$pact of the $aterial pre"ented on the reader. The hu$an
$ind, unlike a co$puter, need" to %e told "everal ti$e" %efore co$$ittin to a certain cour"e of
action.
.epeat the central $e""ae of what you write "everal ti$e". The hu$an $ind i" not at ea"e when
confronted with a 7fire and foret5 type of $e""ae.
;ow, without lookin %ack at what wa" written a%ove ive a "u$$ary of what wa" "aid in "ection
2 3atin2 7i" not followed5 i.e. "o$ethin that i" not i$portant for the under"tandin of the "u%"e!uent te#t, %ut $erely
a "ide track of additional infor$ation.
3 Bu"t read "o$e cla""ic rhetoric te#t" to under"tand what ) $ean. Socrate" "hould rin a %ell even without readinA
Bernhard Spuida, 2002 2
F. )t won5t %e repeated here. 4an you recall the topic of the la"t "u%"ection of "ection FG 'hat
nu$%er wa" that "u%"ectionG
SeeG
&. Matters o Style
Thi" "ection will %e concerned with the little thin" that will hopefully turn accepta%le technical
writin into ood writin. There i" a nu$%er of "ee$inly "$all and uno%tru"ive 7do5"5 and 7don5t"5
that need to %e watched out for con"ciou"ly even thouh they "ee$ to %e o%viou".
The followin $aterial i" not sorted by relevance. ,ou will 0u"t find thin" a" they ca$e to $ind,
read throuh it and con"ider it a" a wi"h li"t for ood writin.
5.1 !itle
The fir"t thin our reader "ee" i" the title. Therefore, the appearance of the title i" of reat
i$portance for the i$pre""ion our te#t leave". The do$inatin factor i" capitali"ation of the word"
in the title. There are "everal 1"chool" of touht1 a" far a" thi" i" concerned2
1. All ords !n Titles Are "apitalised
2. Only the first word is capitalised
=. nothing is capitalised
F. #irst ord and all Nouns are capitalised
<f the"e, ) per"onally reco$$end nu$%er F
F
, a" it i" the "tyle u"ually choo"en for "cientific
pu%lication". ;u$%er" 1 and = are u"ually %ad for the reada%ility of the title. )n any, ca"e, once you
have cho"en a "tyle, "tick with it. No e$ceptions to the rule%
'hen nu$%erin title", con"i"tency i" al"o a $u"t. )f you "ettled for a certain "che$e, "tick with it!
9"ually the nu$%erin "tyle" "ue"ted %y your te#t proce""in "oftware H %e that 3aTeI, <pen
<ffice or what ever el"e H of choice repre"ent "en"i%le "che$e".
5.2 &ig Words
%on!t go above your station. It may well be tempting to employ vocabulary gleaned from some
obscure manual of language, obfuscating your intent by billowing clouds of rhetoric smoke, this
however will most certainly induct the reader!s total non&comprehension of your text.
By now it "hould %e clear what the na$e of the a$e i"2 in the ca"e of two iven word" of the "a$e
$eanin, prefera%ly u"e the "i$pler one. 'ith one e#ception2 "hould the 7%ier5 word %e clearer a"
to it" $eanin, u"e that.
4 -nd u"e it for thi" Tech ;ote.
Bernhard Spuida, 2002 2
-nd when you find your"elf in the 7Bi 'ord 8a$e5, al"o check the lenth of your "entence".
There "ee$" to %e a correlation %etween the two.
However, you will find that u"in only the "$alle"t po""i%le word to refer to a concept will $akin
your writin look dull. - %it of variety never hurt".
5.3 't(s...
)t5" often a $atter of confu"ion for non:native "peaker" to decide when to u"e 7it"5 and when to u"e
7it5"5. The for$er i" the enitive of 7it5, the latter i" a contraction of 7it i"5. Si$ple. 'hen in dou%t,
check %ack here.
-nd prefera%ly write 7it i"5, a" thi" $ake" for %etter "tyle than 7it5"5, without too $uch e#tra typin
effort. Thi" way, the pro%le$ of what for$ to u"e will vani"h auto$aically, anyway.
5.4 An ($(
)t i" of cour"e "o$ewhat te$ptin when tryin to write ood Enli"h to u"e 7a5 and 7an5 in
accordance with the "i$ple a""u$ption that a! is to be used before consonants and an! before
vowels. Thi" i" not in accordance with the rule" of proper Enli"h. Si$ple *a""u$ed+ rule" u"ually
have e#ception" to prove the$ in eneral. The e#ception in thi" ca"e i" with vowel"2
An apple
An exception
An idea
A useless rule but
An uppercase letter
Thi" i" of cour"e a $ere rule of thu$%
>
. Eor the full "tory refer to a "tyle $anual "uch a" 7The
Jin5" Enli"h5.
5.5 Do not use (don(t(
The u"e of contracted neated ver%" i" "o$ethin that "hould not %e done in ood technical writin.
'ritin out a neation in full doe" not take $uch effort on the writer5" part and leave" the
i$pre""ion of a writer carin a%out hi" "tyle. Should he al"o %e the coder of the prora$
docu$ented, attention to "uch detail" will al"o affect the perception of the !uality of hi" codin
"tyle %y the reader.
So2 no won5t, can5t, don5t, i"n5t, aren5t, couldn5t, "houldn5t
-nd never, ever2 ain5t, "han5t
5 ) ue"" you "ee where the eneral drift oe"G
Bernhard Spuida, 2002 2
5.) C$n* could* etc.
4o$in fro$ a 8er$an lanuae %ackround will lead to a very "pecific pro%le$
K
with the variou"
$eanin" of the ver"atile 8er$an au#iliary ver% 7kLnnen5 when tran"latin it into Enli"h.
'an2 the a%ility to perfor$ an action & after having initialised foo, we now can
call bar(ba)*
'ould2 a po""i%ility, or rarely in the ca"e of technical writin, the pa"t ten"e of can
& in the case of an exception being thrown, we could catch it, or dismiss it.
+ay2 a "peculative po""i%ility & in future versions of foo, we may implement
bar(*.
+ight2 an alternative & instead of calling foo(*, we might call bar(* when the
following conditions , are fulfilled.
Should2 a future, not i$$ediate, option & if ever foo becomes obsolete, we should
consider implementing bar
5.+ ,$tivisms
)n eneral, %e "u"piciou" of 7too o%viou"ly natural5 tran"lation" of word" fro$ your native tonue
into Enli"h. E.., the 8er$an 7Jonkurren@5 will tran"late to Enli"h a" 7co$petition5, not a"
7concurrence5 a" $iht %e naively a""u$ed. 8et a ood dictionary and check it often, read Enli"h
te#t" you are already fa$iliar with in your tonue & no $atter whether that te#t i" oriinally
Enli"h tran"lated to your native tonue or vice ver"a
M
. /refera%ly "tart with "o$e favourite %ook of
your" & %e that 7The 3ord of the .in"5, 78ri$$5" Eairy Tale"5 or 78Ldel, E"cher, Bach5 or even
co$ic "trip" or whatever el"e ha" taken your fancy.
9nder"tandin word" properly $atter". 'hen in dou%t a%out the actual u"e of a word with "everal
potential $eanin" in tran"lation, check with a native "peaker or refer to a ood reference dictionary
"uch a" the 7<#ford5. So$e online re"ource" for dictionarie" are iven in "ection M.
5.- "go !rip
Never, ever, use the word &!' in technical writing. )t i" anathe$a. 'e are dealin with o%0ective
$atter", not per"onal opinion". 7)5 $ay only %e u"ed when voicin very per"onal opinion" which
u"ually do not %elon into a docu$ent of technical i$portance H when di"cu""in de"in deci"ion"
$ade %y you, 7)5 $ay %e u"ed leiti$ately, %ut not when de"cri%in a technical detail "uch an in
interface. 'hen enaed in a fla$e war, 7)5 i" perfectly fine
N
, %ut not anywhere el"e near a technical
topic.
Should you however feel a %urnin ure to u"e 7)5, "witch over to the pa""ive voice or third per"on
0 /ro%le$" "pecific to other lanuae" $iht %e di"cu""ed in future ver"ion" of thi" docu$ent.
1 The for$er ca"e i" prefera%le, of cour"e.
2 -" for fla$in, )DH< i" a pleona"$, )D< "uffice" perfectly well & no personal opinion is humble. Thi" now
wa" a perfect e#a$ple of a 7non "e!uitur5 footnote.
Bernhard Spuida, 2002 2
writin.
Turnin to i$per"onal writin worked well for 4ae"ar, when he wa" ivin his account of his
personal acco$pli"h$ent" in the 8allic war" & thi" account i" con"idered cla""ic literature, even
thouh it in fact i" very technical writin. The pa""ive voice i" to %e avoided in eneral, a" it $ake"
for tirin readin, %ut in "uch ca"e" a" we are now di"cu""in, it i" prefera%le to endle"" 7) thinkA, )
con"ider thi" to A, ) didA5.
'henever po""i%le, u"e 7we5 to fore a %ond %etween you and the reader. Thi" will ive a feelin of
7%ein in it toether5. 4la""ical technical writin i" very $uch %ound and i$per"onal "tyle in
eneral. Thi" nowaday" i" no loner true. But "till, technical writin i" not a 7fa$ily thin5!
5.. When to use (if(
4onditional clau"e" $ay %e %eun with 7when5 or 7if5. 4onfu"ion "o$eti$e" co$e" fro$ the
pro%le$ of when to u"e which. 'ith a %it of thinkin, the di"tinction %etween the"e two ca"e" i"
"i$ple2
-hen2 u"ed in ca"e" of a te$poral conditional & when the sun rises, the cock crows
If. u"ed in the ca"e of a cau"al conditional & if we manage to get out of this text alive,
5.1/ !his Sentence does overdo it
9"in 7do5 a" an au#iliary ver% u"ually doe" $ore har$ than help. )t tend" to overe$pha"i"e
"entence" & e"pecially with 7weak5 ver%" "uch a" 7have5 it ive" the i$pre""ion of speaking /ust
that little bit too loud. 9"in 7do5 a" in the introductory "entence of thi" pararaph a" a ver% %y it"elf
i" in order. But it doe" ive a certain o%no#iou" !uality of overa""ertivene"" to your writin if you
do u"e it a" an au#iliary ver% when you definitely do not need to u"e it to "ay what you do want to
"ay. ;ow that doe" "ettle thi" point, doe" it notG
5.11 !ime is on our side
-lway" try to keep the *ra$$atical+ ten"e of technical docu$ent" in the pre"ent. /a"t ten"e ouht
to %e out of the !ue"tion, a" we enerally are not concerned with pa"t develop$ent". The future
u"ually al"o i" %eyond our "cope, a" we do not yet know what future revi"ion" of our prora$ will
%rin.
5.12 Consistenc0
Be con"i"tent in the u"e of either Briti"h or 9S:enli"h "pellin. ;ever "witch in"ide any iven
docu$ent. E#a$ple" of difference in "pellin %etween tho"e two are2
British US
4olour 4olor
4o:operation 4ooperation
Bernhard Spuida, 2002 2
4u"to$i"ation 4u"to$i@ation
-l"o, once you choo"e a iven technical ter$ to $ean one thin, u"e it only in that one "en"e. (o
not redefine%
5.13 "ditor(s pet peeves
-t "o$e point in any writer1" life co$e" the $o$ent where hi" work i" "u%$itted to an editor. Thi"
%reed of per"on doe" have a lot of e#perience with lanuae and the co$$on weakne""e" of the
technical writer. <ver ti$e it ha" %eco$e clear that the "a$e $i"take" are $ade aain and aain. So,
"ave the$ ti$e and your"elf hu$iliation %y followin the li"t %elow. )t contain" additional $aterial
not covered a%ove.
To $ake thin" ea"ier, the li"t i" orani@ed %y topic. The $o"t i$portant i""ue" or the $o"t
co$$only $i"u"ed ter$" are bolded. The word" in thi" li"t are "uppo"ed to %e "pelled a" printed
here, includin capitali"ation, hyphenation or lack thereof, and "eparated or not a" iven. -l"o note
that 9S:enli"h i" the reference here, a" oppo"ed to the other te#t
O
, a" al$o"t all technical writin i"
pu%li"hed %y -$erican pu%li"hin hou"e".
&.1#.1 'rammar and (ogic
allow v" ena%le2 /eople allow( o%0ect" ena%le. So$e editor" are $ore "trinent
a%out thi" rule than other". : 8eorie allowed $e to %orrow hi" 4C. The prora$
enabled $e to create a "tunnin docu$ent. ,ou $iht al"o con"ider to u"e let a"
"ynony$ for allow. : He let $e %orrow hi" 4C.
althouh v" while v" wherea"2 9"e while only when de"cri%in the action of doin
two thin" "i$ultaneou"ly. 9"e although and whereas for contra"t.
#igures2 The fir"t reference to a fiure "hould alway" %e %efore it i" pre"ented.
En"ure that the "pellinof ter$inoloy in fiure" i" "a$e a" in the te#t. 4aption"
*plea"e re$e$%er to include the$+ "hould %e infor$ative "entence". : %ad caption2
The Eile <pen dialo %o#. ood caption2 )n the Eile <pen dialo %o# we ... 'hen
referenced in the te#t with a "pecific nu$%er, the ter$ 1Eiure1 i" alway"
capitali@ed.
graphic 3n4) The noun form usually takes a singular erb.
raphic" *ad0+2 9"e graphics a" an ad0ective in relation to the field of raphic art or
raphic de"in : raphic" file i" ok.
once v" after v" when2 9"e once for ti$e reference". 9"e after to "how that an
event ha" already taken place. 9"e when to "how action" or event" that are
occurrin "i$ultaneou"ly.
over v" $ore than2 0ver denote" cro""in a %arrier or e#ceedin a li$it. +ore than
5 ;ow, that i" $y per"onal deci"ion ) choo"e to $ake a" the author of thi" Tech ;ote.
Bernhard Spuida, 2002 2
!ualifie" a nu$%er. : She ha" worked $ore than K0 hour" thi" week.
precedin v" previou"2 1receding $ean" i$$ediately %efore in ti$e and place.
1revious $ean" "i$ply earlier, prior, or %efore, %ut not nece""arily i$$ediately
%efore. Eor e#a$ple, if the current $onth i" Bune, the precedin $onth i" Day(
previou" $onth" are Banuary throuh -pril.
"ince v" %ecau"e2 9"e since for ti$e reference". 9"e because when e#plainin the
rea"on" why "o$ethin happened.
There is, There are) *ere is, *ere are2 Sentence" "tartin with thi" con"truction
are u"ually $ore clear and le"" wordy if they1re rewritten.
&.1#.2 Spelling and Terminology
above, below2 -void thi" ter$inoloy when referrin to fiure" or other reference".
)n"tead, %e "pecific *"ee Eiure 2F.2+ or u"e preceding, following, next and "o on.
See al"o preceding.
%ackward, toward, forward *no P"P on any of the"e word"+
check %o#, check $ark
%ack up *v+( %ackup *n+
clip art
4lip%oard
4o$puServe
4ontrol /anel
4trl key *"pelled a" it i" on the key%oard+
4trlQ-ltQCelete v" 4trl:-lt:Celete2 <n the /4, key"troke "e!uence" are "eparated
%y plu" "in". )n Dac te#t", "e!uence" are "eparated %y hyphen". Thi" however, i"
"u%0ect to variation dependin on the editor1" preference".
de"ktop
disc v" dis+2 9"e disc when referrin to a 4C or an optical( 9"e disk when
referrin to a = 1?2: or > 1?F:inch di"k. ;ever u"e diskette.
dou%le:click, riht:click, left:click *alway" hyphenated a" ver%+
drop:down *ad0, n+( drop down *v+
email, no hyphen, no capitali@ation
filename
Bernhard Spuida, 2002 2
home page
hotkey *one word+2 Dake "ure that hotkey" are $arked in the chapter". Hotkey" are
indicated typoraphically.
HTD32 Hyperte#t Darkup 3anuae *notice that the PtP in 2ypertext i" lowerca"e+
inline
intranet i" lowerca"e( )nternet i" upperca"e
)S/2 )nternet "ervice provider *no need to $ake the P"P and the PpP upperca"e+
+eyword
lo in?loin v" lo on?loon2 Both for$" are accepta%le, %ut %e con"i"tent. -" a
ver%, log in or log on are two word". -" an ad0ective, login and logon are one
word.
-easurements
%p" %it per "econd
8H@ iahert@
H@ hert@
JB kilo%yte
J% kilo%it
J%p" kilo%it" per "econd
JH@ kilohert@
DB $ea%yte
D% $ea%it
D%p" $ea%it" per "econd
DH@ $eahert@
$" $illi"econd
-" for Jilo%yte", %e con"i"tent in u"in either deci$al *1JR1000+ or power of two
*1JR102F+ notation. The for$er i" to %e preferred for phy"ic", the later for
co$puter "cience conte#t". Thi" al"o hold" true for hiher power" *$ea, ia,
tera, peta+.
$enu %ar
multi, non, re, sub, and co prefi#e"2 )t1" al$o"t alway" "afe to a""u$e that you
don3t need to hyphenate the"e word". *Eor e#a$ple, the correct "pellin i"
Bernhard Spuida, 2002 2
$ulticolu$n, not $ulti:colu$n.+ - few e#ception" to note are a" follow"2
re"ort v" re:"ort2 4esort $ean" a place of retreat( re&sort $ean" to "ort
aain.
recreate v" re:create2 4ecreate $ean" to cut loo"e( to play. 4e&create
$ean" to create aain.
re"ent v" re:"ent2 4esent $ean" to "how di"plea"ure or indination
%ecau"e of a feelin of %ein in0ured or offended. 4e&sent $ean" you "ent
"o$ethin aain.
There are a few e#ception" in Briti"h u"ae thouh, "uch a" co:operation. Settle the
reference "pellin conte#t once and for all when you %ein writin.
Net : upperca"e when referrin to )nternet, .N.T or .net : all upper or lower ca"e
when referrin to the Dicro"oft technoloie", %e con"i"tent with the choice for the
latter ter$.
new"roup
offline, online
offscreen, onscreen
pathna$e
/lu and /lay
/o"tScript
pull:down $enu
ScanCi"k
scrollbar
"et up *v+( "etup *n, ad0+
/pacebar
"tatu" %ar
Ta%le"2 Be "pecific when titlin ta%le", and u"e "entence "tyle capitali@ation *only
fir"t word and any proper noun" are capitali@ed+ for ta%le head". -" with fiure",
the word Table "hould %e capitali@ed when a "pecific ta%le i" %ein $entioned
*Ta%le F.>+, %ut lowerca"e when the reference i" eneric *The followin ta%le... +.
-n endin period i" no loner u"ed after the ta%le nu$%er in any "erie" *Ta%le F.>
i" correct( Ta%le F.>. i" incorrect+.
tas+bar
terminology2 4on"i"tent u"e and capitali@ation of ter$inoloy i" i$portant. -
Bernhard Spuida, 2002 2
novice reader a" well a" a eneral tech editor won1t alway" have the knowlede or
the "oftware a%out which you write and thu" won1t alway" %e a%le to catch
technical incon"i"tencie".
title %ar
ToolTip, ScreenTip
TrueType font
9;)I
up:to:date *alway" hyphenated+
0R12 unifor$ re"ource locator *PuP "tand" for unifor$, not univer"al+.
9"enet
username
eb : i" alway" upperca"e+
wi@ard2 9"e upperca"e PwP when talkin a%out "pecific wi@ard and lowerca"e PwP
when talkin a%out eneric
worldwide *one word, unle"" referrin to 'orld 'ide 'e%+
) $ecommended $eading
<f cour"e no co$plete li"t of %ook" on "tyle can %e iven here. The "election $u"t %y nece""ity %e a
per"onal one. So ) will 0u"t li"t a few %ook" ) found u"eful for $y"elf2
6trunck 7 8hite) /The ,lements of 6tyle"
/The %hicago 6tyle manual"
/The 9ing"s ,nglish"
6tephen 9ing) /.n 8riting" 3:ood ideas about writing in general# not technical. (nd a nice bit of
autobiography# too.4
6ome books that are well written and will gie some idea of what can be done)
.o%ert D. /ir"i, 7Sen and the -rt of Dotorcycle Daintenance5 *-n intere"tin %ook a%out
$otorcyclin, ,the hu$an p"yche, 7!uality5 and & a little & a%out technical writin, all well
written+
Coula" .. Hof"tadter2 78Ldel, E"cher Bach H an Eternal 8olden Braid5 *So$e of the fine"t writin
ever on the concept of 7Strane 3oop"5 which $anae" to et "o$e rather technical point" of
-) and prora$$in acro"" without %ein %orin+
Conald Jnuth2 7The TeI %ook5 *<ne of the fine"t "oftware $anual" ever written. Even the $ore
arcane a"pect" of TeI are clearly e#plained in an entertainin way+
Bernhard Spuida, 2002 2
The ;(< manuals# a.k.a. /The .range 8all" 3Tons of paper# the best set of software documentation
eer. =uch better than most man pages and galaxies ahead of -%>software documentation4
* +nline $esources
So$e online tran"lation and dictionary re"ource"2
htt"5&&666.tecnologi(.net&lai(icon&
htt"5&&dict.leo.org&
htt"5&&6667tg6.df8i.de&96inter&lang&angli:isms7de.html
htt"5&&666.linguadict.de&
htt"5&&666.dictionary.com&
htt"5&&6ombat.doc.ic.ac.u8&foldoc&
htt"5&&666.oneloo8.com&bro6se.shtml
htt"5&&666.tu(edo.org&9esr&;argon&
-" you will notice, "o$e of the"e refer to i""ue" "pecific to the 8er$an lanuae. Even if you are
not a native "peaker of 8er$an, the"e will illu"trate "o$e of the %a"ic pro%le$" with nativi"$".
Bernhard Spuida, 2002 2