| Authors of technical paper sometimes seem to be so obsessed
with equations and graphs that they forget that a technical paper is
by, for, and about people: themselves, their readers, and other
authors. Dealing courteously and consistently with these participants
-- who have not all asked to participate -- makes your paper more
civilized.
Objects also have names: but naming them too much or too little can
make your paper very difficult to read. | |
|
| Whether you are using "we" ("we did this"
etc.) or the passive voice ("it was done", etc.), you must be
consistent. If you are using the passive, search for "we" and reword
to eliminate it if you find it. If you are using "we", check for
occurrences of "was", which may correspond to lapses into the passive
voice. |
|
|
| Charlotte Brontë's phrase "Reader, I
married him" is a cliché of Victorian fiction. In modern
novels, and technical writing, it's quite rare to refer directly to the
people reading your words. But if it does become necessary, then it's
probably better to use "readers", rather than than "you", which seems
blunt. (The word "readership" can also be useful on occasion.) If you
are working on graphics or video, then "viewers" may be a relevant
concept. The word "audience" seems to tempt some authors but, strictly,
it must refer to people who are listening to something, and it's nor
very likely that your paper will ever be declaimed to a real
audience. |
|
|
| Mentioning other authors by name
improves the feel of your paper and is a politeness your colleagues
who, you hope, will be writing about your work one day. Here's how to
do it elegantly: |
| * | Single
authors are easy, e.g. "Smith [1] reported...". |
| * | Two
authors should both be named, e.g. "The groundbreaking technique due to
Smith and Jones [2] suffers from certain
drawbacks...". |
| * | If
there are three or more authors, the "et al" form comes in handy,
"Smith et al [3] have demonstrated...". (You can write it "et al." if
you want to be totally correct, but the full stop is often omitted and
that makes things look a bit neater.) |
| * | If a
group has produced several papers referring to a single system or piece
of work (and how often this happens!) then phrases like "The Frogspawn
system [4,5] is an example of..." or "Well-known work at Smith
University [5,6] has established..." will do the job. |
| * | If
there are two or three similar papers, then it is allowable to write
something like "Recent work [7,8,9] has focused on...". But avoid
stretching this out to five, ten or even more references. A list of
references is not a bibliography: a citation should give the reader a
clear idea how the contents of an individual cited paper relate to the
one that they are reading. What I call 'bulk citation' is lazy and
simply invites a referee to say either a) "the literature survey
is inadequately detailed" or b) "there are too many unnecessary
references", which are two sides of the same coin. |
| * | In
general, anything in brackets is a comment, with its own internal
grammatical logic, and bracketed material, including citations, should
not be expected function as a part of speech in the main text. So you
should avoid using a citation as a noun, like this: "It has been shown
in [10] that...". That path soon leads to nonsense such as "In recent
work by [11], we see that...". |
| -» | It is usually an
easy job to visit all the citations in a manuscript. Search for "[", or
for "\cite" if you're using LaTeX. |
|
|
| It is important to recognize that all acronyms
are not equal. Some, like "UN" and "CD" are currently as well-known as
proper English words. (Indeed, they are better known, because they
occur unchanged in other languages.) Others, such as "API" or "APU",
are quite widely known in technical circles. Yet others are restricted
to a particular specialism. And the most dangerous ones are those that
the authors of a paper invent for themselves. It is possible to make a
paper almost illegible by the enthusiastic invention and deployment of
new acronyms. |
| * | Never
use acronyms just to avoid typing. If necessary, use a short
placeholder while you are drafting the manuscript, and afterwards
search and replace to reinstate the full phrase throughout the
manuscript. |
| * | Think
who might read your paper. If you are using any acronyms that might not
be obvious to any reader, write them out in full the first time that
you use them. But remember that not all readers will want to read the
whole paper: in fact, most will not. Pages full of acronyms make it
very difficult to browse a paper, which effectively cuts the number of
people who will bother with your work. |
| * | Make
sure that the typesetting differentiates acronyms from variables and
other quantities. |
| * | There
are two common formats for explaining acronyms: e.g. "the PNG (portable
network graphics) file format" or "the portable network graphics (PNG)
file format". The first is perhaps a bit more logical. In any case,
use one consistently. |
| * | There
is no need to capitalize the written-out version of an acronym
unless it is a proper or trade name, e.g. "APL (A Programming
Language)", is correct, but in "CPU (Central Processing Unit)" the
capitalization is unjustified, and you should write "CPU (central
processing unit)". |
| * | If you
are thinking of defining a lot of new acronyms, then think
again! However, it is possible that just one new acronym, carefully
defined, frequently used, and relating to the central message of your
paper, would be justified. If a new acronym represents a significant
insight, it might just catch on. |
| * | One of
the problems with acronyms is that, because they are not proper words,
they do not inflect to show when they have become different parts of
speech, for instance "NC" sometimes means "numerical control",
sometimes "numerically controlled". Plurals and possessives can be
formed with a small "s", e.g. "RAMs are cheaper", "the RAM's
connectors were deformed", or "the RAMs' connectors were all deformed".
As you can see, possessives look a bit odd, and should be sidestepped
if possible. |
| * | Not
all the English names for letters of the alphabet start with the same
letters. For instance, the letter "N" is pronounced "en". Some acronyms
are pronounced like the letters of which they are composed. For
instance we say "en-cee", for "NC". Therefore we say "an NC machine
tool", not "a NC machine tool". However, other acronyms are
pronounced like words. So we write "a NAND gate" and not "an NAND
gate". It is best to avoid acronyms that make pronouncable words
(unless, perhaps, you are hoping it will be adopted as a snazzy name
for your technique). Presentation problems without any real solution
can be easily result. For instance, suppose you invent two quantities
called "standard numerical measure" and "standard algebaic measure",
and go for the acronyms "SNM" and "SAM". Then do you write "an SNM and
a SAM" or "an SNM and an SAM"? Neither is good. |
| -» | Search to see how
often every acronym is used. The less familiar an acronym, the more
necessary it must be to justify the reader's effort in learning it.
Unfamiliar acronyms -- especially ones that you have defined
yourself -- that only come up only come up a few times (or are
awkward to use) should be replaced by the full name that they stand
for. |
| -» | If you still have
lots of acronyms then consider taking further action to help the reader
by systematically 'refreshing' every acronym (except the very
obvious ones) at the start of each major section of the paper. This is
simply done by replacing the first occurrence of each acronym with its
full name. Assuming the acronym itself is used again quite soon, there
is no need to tie the name to the acronym (i.e. by providing both, with
one in brackets) as you would do if it were being introduced for the
very first time. |
| -» | Finally, consider
providing a table of acronyms with their meanings. |
|
|
| Unnecessary capitalization of technical phrases is
something that is often done by people who have just started work on a
topic; because they find the phrases new and exciting. If you want to
look experienced, don't do it. In particular, note that disciplines and
subjects (e.g. "Machine Vision" or "Differential Geometry") do
not need capitals (i.e. they're wrong as shown
here). |
|