| A UK author called Lynn Truss has recently made a large amount
of money from a bestselling guide to good English called Eats,
Shoots and Leaves, a title which neatly demonstrates how a
misplaced comma can cause havoc with the sense of a phrase.
The same is true in technical writing. However, in a technical paper
quite simple sentences are acceptable; and many awkward constructions,
such as direct speech, are very rarely required. It is also possible to
sidestep some problems of punctuation -- and of grammar -- by relying
more heavily on equations, tables and lists.
Here are some more specific suggestions.
| |
|
| Because they are directional, brackets are
easy to read. They can usefully replace pairs of dashes, and sometimes
pairs of commas, if a sentence is becoming very long. |
| * | There
should be no punctuation marks immediately before either an opening or
a closing bracket. (The exception is a full stop, which appears when
an entire sentence is in brackets: like this one.) |
| * | Check
the appropriateness of punctuation around parentheses by imagining that
the brackets and everything inside them disappears: the surrounding
sentence should still make grammatical sense and be punctuated
sensibly. |
| * | Nesting parentheses, should be
done with square brackets "([ ])". But since square brackets are
usually used for citations, this is confusing. The answer is to
eliminate all nested parentheses by appropriate rewording. (Dashes,
otherwise not recommended, can have a use here.) |
| * | Explanatory phrases starting
with "i.e." or "e.g." are almost always made more readable by being put
into brackets. |
| -» | An obvious
mechanical check is to ensure that brackets match. Some editors (e.g.
those for LaTeX) do this automatically. |
|
|
| It is possible to write a whole book without
colons and semi-colons. If you are unsure about these punctuation
marks, then search for them and replace each one by a comma or a full
stop, as appropriate. |
| A colon is often useful to end the last
sentence before a list or an equation, especially if you are using the
phrase "as follows". |
|
| Dashes |
| Dashes have several different and conflicting
meanings. They are probably best avoided in technical writing. (However
they can make a small comeback to avoid nesting brackets -- see above.)
|
| * | Note
that numerical ranges (e.g. page numbers, such as "pp. 23-45")
should really be separated by a short dash (endash) rather than a
hyphen. |
| -» | Search for
dashes, and replace them with commas or parentheses, or split the
sentence into several parts. |
|
| Hyphenation |
| Be generous with hyphens, in phrases such as
"graph-theoretic", "vector-valued" etc. Remember you may need a hyphen
when a phrase is used as an adjective (e.g. "real-time systems")
although the hyphen may be omitted when the same phrase is used as a
noun (e.g. "done in real time"). Note that it is usual not to
put a hyphen after words ending in "ly" |
| -» | Depending on
context, you may find it worth searching for some of the following
words, which often occur in forms that should be hyphenated:
| | aided, axis, based, bi,
computer, coordinate, data, dimensional, free, high, inter, iso, low,
multi, non, order, orientated, parameter, piecewise, point, semi,
space, specific, sub, super, theoretic, time,
well. |
|
| -» | Search for "ly-".
Anything that comes up (except "fly-fishing"!) probably needs
fixing. |
|
| Possessives |
| In technical writing, try to avoid the
possessive formed by an apostrophe and "s". A phrase such as "the
program's variables" can easily be reworded as "the variables used in
the program". There are some exceptions, often associated with proper
names where the apostrophe needs to be retained. Replacing "Bessel's
function" by "the function of Bessel" is not
idiomatic. |
| -» | Search for "'s"
and reword unless the apostrophe is essential. |
|