5. Matters of Style
This section will be concerned with the little things that will hopefully turn acceptable technical writing into good writing. There is a number of seemingly small and unobtrusive ‘do’s’ and ‘don’ts’ that need to be watched out for consciously even though they seem to be obvious.
The following material is not sorted by relevance. You will just find things as they came to mind, read through it and consider it as a wish list for good writing.
5.1 Title
The first thing our reader sees is the title. Therefore, the appearance of the title is of great importance for the impression our text leaves. The dominating factor is capitalisation of the words in the title. There are several 'schools of tought' as far as this is concerned:
1. All Words In Titles Are Capitalised
2. Only the first word is capitalised
3. Nothing is capitalised
4. First Word and all Nouns are capitalised
Of these, I personally recommend number 44, as it is the style usually chosen for scientific publications. Numbers 1 and 3 are usually bad for the readability of the title. In any, case, once you have chosen a style, stick with it. No exceptions to the rule!
When numbering titles, consistency is also a must. If you settled for a certain scheme, stick with it! Usually the numbering styles suggested by your text processing software – be that LaTeX, Open Office or what ever else – of choice represent sensible schemes.
5.2 Big Words
Don’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 should be clear what the name of the game is: in the case of two given words of the same meaning, preferably use the simpler one. With one exception: should the ‘bigger’ word be clearer as to its meaning, use that.
And when you find yourself in the ‘Big Word Game’, also check the length of your sentences. There seems to be a correlation between the two.
However, you will find that using only the smallest possible word to refer to a concept will making your writing look dull. A bit of variety never hurts.
5.3 It's...
It’s often a matter of confusion for non-native speakers to decide when to use ‘its’ and when to use ‘it’s’. The former is the genitive of ‘it’, the latter is a contraction of ‘it is’. Simple. When in doubt, check back here.
And preferably write ‘it is’, as this makes for better style than ‘it’s’, without too much extra typing effort. This way, the problem of what form to use will vanish automatically, anyway.
5.4 An 'a'
It is of course somewhat tempting when trying to write good English to use ‘a’ and ‘an’ in accordance with the simple assumption that ‘a’ is to be used before consonants and ‘an’ before vowels. This is not in accordance with the rules of proper English. Simple (assumed) rules usually have exceptions to prove them in general. The exception in this case is with vowels:
• An apple
• An exception
• An idea
• A useless rule but
• An uppercase letter
This is of course a mere rule of thumb5. For the full story refer to a style manual such as ‘The King’s English’.
5.5 Do not use 'don't'
The use of contracted negated verbs is something that should not be done in good technical writing. Writing out a negation in full does not take much effort on the writer’s part and leaves the impression of a writer caring about his style. Should he also be the coder of the program documented, attention to such details will also affect the perception of the quality of his coding style by the reader.
So: no won’t, can’t, don’t, isn’t, aren’t, couldn’t, shouldn’t
And never, ever: ain’t, shan’t
5.6 Can, could, etc.
Coming from a German language background will lead to a very specific problem6 with the various meanings of the versatile German auxiliary verb ‘können’ when translating it into English.
• Can: the ability to perform an action — after having initialised foo, we now can call bar (baz)
• Could: a possibility, or rarely in the case of technical writing, the past tense of can — in the case of an exception being thrown, we could catch it, or dismiss it.
• May: a speculative possibility — in future versions of foo, we may implement bar().
• Might: an alternative — instead of calling foo(), we might call bar() when the following conditions … are fulfilled.
• Should: a future, not immediate, option — if ever foo becomes obsolete, we should consider implementing bar
5.7 Nativisms
In general, be suspicious of ‘too obviously natural’ translations of words from your native tongue into English. E.g., the German ‘Konkurrenz’ will translate to English as ‘competition’, not as ‘concurrence’ as might be naively assumed. Get a good dictionary and check it often, read English texts you are already familiar with in your tongue — no matter whether that text is originally English translated to your native tongue or vice versa7. Preferably start with some favorite book of yours — be that ‘The Lord of the Rings’, ‘Grimm’s Fairy Tales’ or ‘Gödel, Escher, Bach’ or even comic strips or whatever else has taken your fancy.
Understanding words properly matters. When in doubt about the actual use of a word with several potential meanings in translation, check with a native speaker or refer to a good reference dictionary such as the ‘
5.8 Ego Trip
Never, ever, use the word ‘I’ in technical writing. It is anathema. We are dealing with objective matters, not personal opinions. ‘I’ may only be used when voicing very personal opinions which usually do not belong into a document of technical importance – when discussing design decisions made by you, ‘I’ may be used legitimately, but not when describing a technical detail such an in interface. When engaged in a flame war, ‘I’ is perfectly fine8, but not anywhere else near a technical topic.
Should you however feel a burning urge to use ‘I’, switch over to the passive voice or third person writing. Turning to impersonal writing worked well for Caesar, when he was giving his account of his personal accomplishments in the Gallic wars — this account is considered classic literature, even though it in fact is very technical writing. The passive voice is to be avoided in general, as it makes for tiring reading, but in such cases as we are now discussing, it is preferable to endless ‘I think…, I consider this to …, I did…’.
Whenever possible, use ‘we’ to forge a bond between you and the reader. This will give a feeling of ‘being in it together’. Classical technical writing is very much bound and impersonal style in general. This nowadays is no longer true. But still, technical writing is not a ‘family thing’!
5.9 When to use 'if'
Conditional clauses may be begun with ‘when’ or ‘if’. Confusion sometimes comes from the problem of when to use which. With a bit of thinking, the distinction between these two cases is simple:
• When: used in cases of a temporal conditional — when the sun rises, the cock crows
• If: used in the case of a causal conditional — if we manage to get out of this text alive…
5.10 This Sentence does overdo it
Using ‘do’ as an auxiliary verb usually does more harm than help. It tends to overemphasise sentences — especially with ‘weak’ verbs such as ‘have’ it gives 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 capitalization, 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. -
• Although vs while vs whereas: Use while only when describing the action of doing two things simultaneously. Use although and whereas for contrast.
• Figures: The first reference to a figure should always be before it is presented. Ensure that the spelling of 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
• 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
• 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 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
• 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)
Recommended
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)
No comments:
Post a Comment