(Non-Geek Escape Route)
Welcome to a reference collection of tips from my documentation reviews on the debian-l10n-english mailing list.
These notes could go on the Debian Wiki, if it wasn't for the fact that typing
a paragraph or two of text into my web browser is enough to remind
me that editing text is easier in a text editor. Besides, I
don't want to have to defend my notes against well-intentioned
sabotage by people who half-remember some piece of mumbo-jumbo
handed down to them by their English teacher; this may be a
prescriptive style guide, but it's one primarily designed to help
people write the way competent native-speakers really do in the
twenty-first century. The idea is that next time I'm
reviewing something claiming to be
I'll just be
able to point at prefabricated summaries of what's wrong with
it. (Yes, that's how I'm highlighting
an unix software
that allows to run an own irc-based proxy
First I'd better get out of the way some
rules with no particular basis in linguistic reality. They
have never been real features of the grammar of English as used
by even the most universally admired writers – they're
delusions propagated by people who want to be able to look down
on all the members of the general public who fail to obey their
imaginary rules. We might nonetheless choose to abide by
these taboos just to avoid the arguments.
restrictiverelative clauses (see C1) with either
that. The myth is that the ones
thatis used are the only grammatical ones.
butto start a sentence. why shouldn't we? It seems to have no trace of a rationale.
I suppose either Alice or Bob must have lost key.
I said I'd decided smoking cigarettesis better than any of the alternatives.
Some prescriptivists insist on usages like
, even though
they're long extinct in most brands of natively spoken
English. Following their advice is a good way of making
yourself sound as if you were brought up on the Lost Island of
none of you
knows whom he would choose if he were I
English offers plenty of opportunities for picking the wrong
word. Sometimes it even seems to be systematic about it;
for instance, it often presents a three-way choice between
-ing noun, plain noun, or
-ation noun, all of them
more or less synonyms (
-ing words can be tricky to
fit into a sentence, since they keep some of their old verbal
-ation words tend to be fancy and abstract.
This one crops up so often I'm putting it right at the top.
do something (as in
can say that
this option allows to compile code
this option allows you to compile code, or
this option allows code compilation, or even
option allows code to be compiled; but if there's no object
immediately after the verb, it's almost certainly ungrammatical
(and the same goes for
permit to). Native-anglophone
readers will know what you mean, but they'll also suspect you've
got a funny accent.
Besides, unless the software is something like PAM, how likely is
it that it literally
allows me to do something otherwise
forbidden? It enables or simplifies doing things, or helps
me do them, or simply does them.
Well known cases where the English word doesn't mean what speakers of most European languages expect.
|beware of…||when you mean…|
Each of the following words has more than one well established idiomatic meaning, so you need to be aware of the possible misinterpretations.
archives, but so are individual .deb files (they're ar archives). There are quite a few technical labels for subdivisions of the Debian archives, including
section. Most of them present opportunities for confusion.
executablesis clearer. If instead you're talking about Debian
binary packages, those are officially so called regardless of whether they contain binary data or ASCII text; even the ones providing kernel source-code count as
sourcepackages. Both kinds are accessed via the kind of
sourceslisted in /etc/apt/sources.list.
graphical, but also more narrowly as
run in a VT login(like startx). And then there are
MySQL servercan be either software or hardware.
file systemthe storage volume presented as a directory hierarchy under some mount point, like /home, or is it the storage format, like NFS? But somehow this one never seems to cause trouble.)
an e-mailan address or a message? (Compare
the IP– an address or a piece of Intellectual Property?) There's some disagreement over the hyphenation of E(lectronic) Mail; my own fingers insist on
e‑mail, but various authorities prefer
online documentationfor an
online gamestored on my /usr partition or their wiki? This confusion is traditional, but not all traditions are worth preserving.
obsoletepackages, but that's the word aptitude uses to mean installed packages with no current version in the archives.
root, from directories to servers to windows (and things are even worse for those of us who pronounce
routeas a homophone). Always make it clear whether you're talking about the administrative login for my addressbook database or whether you mean the system superuser.
, for example) slip through untranslated.
) is a particular giveaway: English doesn't have a generally recognised abbreviation for
respectively, because we hardly ever use the word. Most of the time the best idiomatic translation is either
e.g.with equivalent English phrases (
such as) can make a text seem subtly less technical, and eliminates the danger of confusing them.
-basedis often unnecessary padding. An
Ajax-app is the same as an Ajax app, a
network-connection is a network connection, a
Qt-GUI is a Qt GUI, and so on.
to login to my PC,
to log in to my PC, or
to log into my PC? Well, the noun is one word, a
login; but for the verb, since you can
log yourself init must be two words (the same rule applies for
shutdown). Then the
in toisn't the kind that means
into; it's just a coincidental sequence of
giving in to temptation), so the form I'd recommend is
log in to.
package managementwhile the latter is
. Instead it's treated as a material –
a piece of malware. Much of the time if you've written
the word you were looking for was
applications. While I'm on the subject, notice that software is installed on a computer, but hardware is installed in a computer.
By which I mean an obviously incomplete survey of syntax, morphology, and so on. If you're looking for apostrophe-pedantry, it's filed under Orthography.
English has four basic types of relative clause.
whereby, or some other
WH-word) preceded by a comma. These are
descriptiverelative clauses, and only add supplementary, parenthetical information; Germans should be careful not to confuse them with the following.
WH-wordwithout a comma. These are known as
restrictiverelative clauses, on the grounds that they define an identifying characteristic of the entity in question. The main problem with them is the fanatical which-hunters who want to have them declared ungrammatical.
that. These are another brand of restrictive relative phrase; they have the advantage of not waving a red flag at the pedants, but then again, using
whowith a human referent tends to sound a bit stilted to many native speakers (including me).
If in doubt, don't overlook the option of cutting it into two or more separate sentences.
Definite versus indefinite versus nothing is far
too complicated to explain here beyond the rule of thumb that the
the is for when both writer and reader
can identify the thing being referred to.
The question of whether it's
the file FOO or
the FOO file is a similar issue of information
management, since the answer is that it's either, depending
mainly on what's news and what's background knowledge:
the pre-foo.d directory,
your .bar2rc file.
the directory /lib/baz-common/scripts,
the command /usr/sbin/update-quuxd.
Non-native speakers also tend to have trouble guessing whether to
refer back to a previously mentioned idea with
that. This can be really difficult (that was an
On the other hand, the rule for whether the indefinite article is
an is clear-cut as long as you ignore the
spellings – what you need to know is how the following
word is pronounced, and whether it begins with a consonant sound
a USB device) or a vowel
Unfortunately, there are a few debatable cases, since some of the
things we may need to refer to don't have established consensus
pronunciations. Is it
a straced process or
an straced process?
An URL or
A mkfs variant or
mkfs variant? Sometimes the same people even
alternate between saying
an /etc/hosts file
There's no room here for a full explanation of the rules of the English tense system (besides, if I said that technically it has a grand total of two tenses I would only confuse people…) but here are some hints for the bits I see causing trouble most often.
Watch out for the subtle distinction between the simple past
tense, which marks things as over and done with, and the perfect
have, which marks them as having
continued relevance (not quite the same thing as being
recent). There are slight differences in usage between
dialects, but basically, a warning message saying
was broken suggests that it is now fixed; a warning message
FOO has been broken implies the opposite.
English has a system of
sequence of tenses, where past
tense marking on a main clause spills over onto subclauses:
said my name was Sam. This can even happen when
the tense mark on the main clause doesn't really indicate past
I could stop tomorrow if I wanted.
used to construction, as in
I always used to get
this wrong, has the annoying quirk of lacking any present
tense equivalent – it would be logical if you could
carry on with
…and in fact even now , but alas, natural languages don't run
on logic! What's more, even when you get the grammar right,
I'm still using
to get it wrong
used to construction can easily lead to
confusion. For example,
the software used to do this
would be fine in speech (since the past-habitual marker is
yoost instead of
yoozd), but it becomes
ambiguous when written down.
Some dialects have complex rules for when you should use
shall rather than
will, but not mine –
grep tells me I only use
shall when I'm quoting
something that includes the word
All of the following things are singular in English (or at least,
it would be grammatically correct to follow them with
here rather than
Either Alice or Bob…
Everybody and everything…
Nothing and nobody…
More than one thing…
Non-count nouns also take singular agreement:
is fallible, and so is
mathematics, or (this
side of 1950)
data. On the other hand,
a lot of
people are here, while
Alice and/or Bob can go
each politician takes singular agreement, and
faces are ordinarily distributed on a one-per-person basis, it's
entirely non-satirical to say
the politicians showed their
Their face would imply it was shared.
Nouns that modify other nouns are usually unpluralisable (just
like the adjectives they resemble), so a collection of managers
of windows is a
window manager collection, not a
But then again, a conference of managers of events is quite
likely to be an
s manager s collection
events managers conference, and I can't
offer any sort of rationale for these exceptions.
Most adjectives can occur either before the thing they describe
or after a linking verb (
lonely Jim is lonely); a few
the sole survivor stood alone versus
). The word
the alone survivor stood sole
own may resemble an adjective, but it isn't allowed to
appear in either position without the support of a possessive
Its own name is fine, but
has to become
a name of its own.
used as adjectives don't behave exactly like natural
adjectives. They pile up immediately before their head
noun, never mixing in with the adjectives to participate in
a simple, .
shell, useful script
dangling modifier is another of those deprecated
constructions that native speakers get away with all the time:
after Interpreted pedantically, this sentence claims
that the bug performed the reinstallation…
reinstalling my PC the bug got
Matters of style are essentially arguable, but if you don't want my advice, you don't have to ask for it.
When people say something is
bad grammar, what they often
mean is that it obeys the grammatical rules of the wrong dialect,
which is a stylistic issue. The real reason for avoiding
slangy or dialectal usages isn't that they're inherently bad,
it's that they're less universally understood, especially by
readers who are themselves non-native-speakers.
As you may have noticed, even though this page is itself written in my usual British-English HTML style, the variety of English it recommends for debconf templates is the one that goes with an en_US locale. Other Debian subprojects use en_GB, or have no standard – and even in package description reviews we're often better off letting people follow whatever standard they know best rather than forcing them to adopt one they're uncomfortable with.
Educated American English isn't completely homogeneous anyway; and
where there's variation we need to avoid confusing or annoying
speakers of either variety. Take for example the
unpleasantly ambiguous phrase
in case. For some
anglophones, the instruction
unplug your PC immediately
just in case of a short circuit
conditionally, if and when a short circuit occurs, unplug your
PC; for others (including me) it means
avert a short circuit, unplug your PC now.
Using an informal register has the advantage that it can give a
friendly impression; but there's also a risk that this chumminess
may be unwelcome in a context where your readers just want you to
get on with conveying information concisely and coherently.
Spoken English tends to leave more things implicit, since a
real-world context normally makes what you mean instantly
apparent. A classic example of a usage that's frowned upon
in formal writing but taken for granted in conversation is the
ambiguous use of
those options that resemble FOO,
possibly excluding FOO itself, and certainly excluding
options unlike FOO? Or does it mean
arbitrary option, such as FOO?
Colloquial English often uses sequences of independent clauses, you just splice them one after another with nothing to signpost how they fit together, they're called run-on sentences, like this, see? Constructions like that are deprecated in writing, but often all that's needed to fix them up is a few commas promoted to semicolons.
Addressing the audience directly with second person
you/your) has advantages and disadvantages – see
F2 – but first person
I/me/mine/we/us/our) in documentation is generally a bad
idea; it's not only informal, it's also confusing. Is the
speaker the upstream author, some random NMUer, or an animated
An excessively formal register should also be avoided.
Convoluted uses of balanced antitheses within multi-line relative
clauses within hypothetical conditionals can be a very concise
way of saying something, but they force readers to do extra work
unpack it. Even when your display of syntactic
knotwork is technically perfect, if it bores everybody into
skipping that paragraph you might as well not have written it.
Long, elaborate sentence structures can increase the risk of
On the other hand once you start breaking everything up into
bite-size chunks there's the danger you'll introduce referential
One should not fail to avoid making a
foolish error and leave the button unpressed
There's a button above the off switch. The
off switch should be recognisable because it's red.
The impersonal pronoun
one (as in
using this emulator
one can play arcade games) almost always strikes me as
hopelessly formal; either replace it with generic
rephrase the whole thing. Similarly, over-reliance on
passive verbs (
a test-tube was heated…) is
generally unpopular. Contrary to its bad reputation, the passive voice sometimes
provides the most natural and direct way of continuing a sentence
walking in the door, I by my friend Pat,
so I went over…); but that's no excuse for saying
please note that it is important that the button should
immediately be pressed when you mean
Revising a sentence to introduce or eliminate a passive construction is an opportunity for syntactic problems to creep in and leave you with your pronouns pointing at the wrong things:
Once FOO has installed BAR, it
should be removed.
Once BAR has been installed, it
should be removed.
Once BAR has been installed, FOO
should be removed.
NOTE that tags saying
NOTE are a bad sign.
Documentation is entirely constructed out of strings of notable
points, tacked together into (preferably) coherent
paragraphs. If you need to sprinkle it with labels saying
READ THIS PART, that probably means it's a bit of a mess.
Gender-neutralising by explicitly saying
he or she is
often clunky (though not as ugly as telling half the human race
they don't count as people). If you want to avoid breaking
the taboo against
they with a singular,
there are some alternatives that avoid the issue:
youis number- and gender-neutral).
Avoid unnecessary redundancy and repetition. Even if it makes sense to refer to the same thing several times, it's considered poor style in English to use the same word repeatedly unless it's deliberate emphasis. This rule can cause a lot of trouble if you're trying to describe how users usually used to use useful userspace usage-monitors…
This is the field where I'm most likely to be bossy, since
languages and writing systems are two different kinds of
thing. Once there's a community of mother-tongue
English-speakers who have grown up talking about
items, complaints from people who say
fewer items are
pointless – it's one of the ways English is spoken, so
it gets to be listed in dictionaries. But orthographies are
artificial rule-systems propagated via schools, and have no
native speakers. If you spell it as
then you're just failing to comply with the
If you run lintian with all the optional bells and whistles turned on it has checks for quite a few common typos.
Yes, I'm an en_GB-er myself, but US spellings strike me
as a clear improvement in the vast majority of cases. The
best known difference is that en_US expands
internationalization, while en_GB mostly uses
internationalisation. However, the OED prefers
-ize (as did
The Times until quite recently), and
there are a few words that are
-ise in both systems,
Other major categories of divergence:
|centre||center||(but always ogre, auger)|
|colour||color||(but always glamour, error)|
|dialogue||dialog||(but always fugue, Prolog)|
|mediaeval||medieval||(but always aerial, query)|
|travelling||traveling||(but always felling, feeling)|
The un-American spelling
programme still exists, as a
British word for TV shows and the like, but these days the
computer variety is always
Package synopses are rather like titles, but that doesn't mean
they take Lots of Upper-Case Letters; the Developer's Reference
recommendation is not to give them extra
capitalisation. This doesn't mean that you should write
gNU, though! We have to distinguish
situational capitalisation, imposed by context, from
lexical capitalisation, which is part of the spelling of a
word. A normal word can vary from all-lower-case to
first-letter-upper-case to all-upper-case depending on factors like
whether it's at the start of a sentence or whether it's in a
newspaper headline. But words like
English involve letters that are inherently upper-case,
written that way regardless of context.
Words with intrinsically lower-case characters are rare
outside the world of science and technology (where it can mean the
But in IT, strings such as
email@example.com often have to be invoked
precisely verbatim, and even strings like
usb may need to be entered in a configuration
file in lower-case. The same logic is often applied to
package names such as
gnome, which may be left uncapitalised at the
start of a sentence in documentation. After all,
apt-get install Exim4 won't work
[my original example there used aptitude, but
that will work on Jessie!]. Rather than insist
on a stylistic policy for this issue that requires people to agree
on some particular obscure analysis, it's safest to advise keeping
package names out of sentence-initial position where possible.
Upstream software project
brand names are a different
matter, and are upstream's decision. If they call it
FooBar we should respect the capitals,
but if their website calls it
the foobar project it's not
clear whether they're leaving it unmarked or declaring it
uncapitalisable. Incidentally, does anybody have any idea
under what circumstances it's appropriate for Debian
documentation to label brand names as registered
trademarks? My own suspicion is that there's never any
serious reason for us to put such labels on anything; if we were
going to get sued for not saying Microsoft®
Windows® it would have happened a decade ago.
One context where I'm happy to see what looks like title-case in
a package synopsis is for things like cups, where
including the expansion as
Common UNIX Printing
System makes it easier to see at a glance that it's
doing double duty as an explanation for the name as well as a
front end tend to become
frontend as the term gets used more.
Programmers are often early adopters of new jargon, so there's
an unfortunate tendency for documentation to be written in a
style that's unfamiliar and offputting for the readers who need
it most. Feel free to talk in your private shorthand on
the development mailing list, but try to stick to the more
newbie-friendly forms (
when you're addressing the wider public.
I know of a couple of gotchas: being
online isn't the same
plaintext is not the same thing as
plain text, a
username is not the same as a
user space. You'd
think the hyphenated versions would make good compromise
candidates, but that rarely seems to work… instead my own
rule of thumb is: if Wikipedia still treats it as two words, that's
what the average reader probably expects.
Structurally complex noun phrases tend to acquire hyphenation not
because they're becoming single words but just to make it easier
to distinguish (e.g.) a
system from a
real time-machine translation-system.
Extra hyphens also occur with phrasal modifiers like
easy-to-use application, but here they serve to mark the
whole thing as a unit; the hyphens aren't needed when the same
phrase appears after a linking verb (
it's easy to
use). You might think the same applies to multi-word
modifiers made up of adverb plus participle, as in
used application, but since these are never structurally
ambiguous a hyphen is considered redundant.
(A cover-term for backticks, apostrophes, and opening or closing single or double quotation marks.)
The rules for apostrophe use are an obstacle course of arbitrary complexities, where errors are usually spell-checker-proof (and the real joke is that they almost never cause ambiguity – we could get along happily with no apostrophes anywhere). English possessive apostrophes are particularly shambolic.
won[o]t(er, yeah). Some style guides call these contractions
colloquial, but that just means they're a century or two out of date.
a package's name,
all the packages' names).
whose name?), so in doublets like
you're/yourthe apostrophe marks the non-possessive.
one's own) does have an apostrophe after all.
There's some debate about the use of apostrophes on inflected
forms of numbers, acronyms, and so on (
1990's). Most style guides recommend
leaving them out (
one OS, many OSs), but this advice isn't
logical style of quotation mark placement, where
punctuation is kept outside the bracketing quotes unless it's
part of the original text, is prohibited by many US style
guides… so let's ignore them in favour of the
And then there's the question of single versus double
quotation marks versus fancy Unicode ones. I
personally prefer to stick to ASCII in contexts where users are
likely to want to do command-line searches or use
copy-and-paste. I also use the
" character by
default, reserving the
' character for use as an apostrophe
or second-level quotation mark. Although that's what I
learned at school, people tell me it's the American style; and by
happy coincidence it's also the style preferred on
d‑l‑e, but as long as a given text is
consistent I won't object particularly. (Well… not
unless you're using
quotation marks, that is. Please don't; I'm sure they would
get typeset into something beautiful if only they were being
post-processed by LaTeX, but sitting there in my terminal
emulator they'll just look rubbish.)
Some writers use single quotation marks not to indicate quotations but as an ASCII workaround for tagging verbatim strings – the sort that I'm HTMLising here in a nonproportional font. Thus for instance they might say that 'remake' is yet another "simple" replacement for 'make'; this is all very well, but trying to apply it consistently would often make text look too fussy.
Lists where some of the items are themselves slightly complex
often benefit from being rephrased (and in particular re-ordered)
for clarity. For instance,
it supports FOO, BAR, and BAZ
with QUUX or QUUX2 is ambiguous in a way that
BAZ with QUUX or QUUX2, plus FOO and BAR is not.
Another tactic is to upgrade the separators between list items
from commas to semicolons:
spam, bacon and eggs, and spam, eggs, bacon,
spam; bacon and eggs; and spam, eggs, bacon, and
Where a list is organised by bullet points, d‑l‑e has developed a sort of house style.
It features: * leading single-indented asterisk (or maybe dash); * semicolon at the end of each item; * final period (full stop).
However, a simpler approach, less integrated into the surrounding text, is still okay by me as long as it's self-evident what it's a list of.
* Independent items * Asterisks * Capitalisation * No other punctuation (or not much)
Lists read more smoothly if items are kept structurally
parallel – usually all adjective phrases, all
noun phrases, or all verb phrases, not a mixture.
Avoid writing them like this. o broken parallelisms! o insufficiently similar; o Don't go together very well
Mind you, if it's only two or three bullet points it might work
better as a plain old sentence; lists with sublists are
particularly worth flattening. And although it's important
to make it clear whether the list is exhaustive, it's easy to
overdo it – there's no need to say
its features , for example, include (but are not
limited to) FOO, BAR, and
BAZ , among many others
&within text is considered informal (though for some reason it's okay for
Baz & Quux, Solicitors). Slash as a shorthand for
oris often worth avoiding too, since it's easily misinterpreted (compare
FOO,usually need an extra (
FOO, BAR, and BAZ.
giga-(and so on) is almost extinct in the UK, but meanwhile we've got
tebibytesto worry about.
(FOO, BAR,to indicate an open-ended list may be standard C syntax, but it isn't common in English prose; use an
etc.instead of an ellipsis.
is the Pope catholic?into something that technically isn't a question, the easiest approach is to transform it into
please specify whether the Pope is catholic.
. Between sentences we're standardising on one space rather than two, which isn't what I'm used to, but for a start it's more resilient against HTMLification.
This is arguably outside the remit of a localisation mailing list, but while we're reviewing a piece of documentation it makes sense to do some fact-checking and general editing.
The setting determines where the dividing line is between things
being technical jargon and general knowledge. TLAs usually
ought to be expanded or explained the first time they're
used – and if they aren't used more than once, why waste
time introducing the abbreviation in the first place? But
that doesn't mean you need to interrupt your DIY Integrated
Circuits HOWTO to explain what a
eg-daemon free download.
e. Writing the description to be clear from the point of view of your users isn't enough – everyone else has to be able to work out
oh, this isn't for me, it's for those EGP proxying nuts!
See the Debconf Spec and the existing Templates Style Guide (now part of the Developer's Reference).
Debconf dialogues should almost never need to mention
debconf, or even
the installer; these are
technical implementation issues that should be transparent to
the user. Besides, mentioning installation in the middle
of an upgrade or dpkg-reconfigure run is just
When you need to give an example hostname, don't give free advertising to myhost.com, randomword.com, or foo.com; use an RFC-compliant one like example.org.
It isn't necessarily appropriate to ask
would you like to
reconfigure your server? if the reader might be a sysadmin
reluctantly following corporate guidelines for software
installations on the company's server. (Second-person
pronouns also tend to make life difficult for translators.)
All you know for sure is that it's up to the reader to answer the
should the server be reconfigured?
See DevRef 6.2.1 to 6.2.3 (and salvaged from the archives, some old guidelines by Colin Walters).
Questions like how the software is implemented and what standards it conforms to can wait. The basic point of a package description is to announce what this .deb is for – what can it do to solve users' problems and make their lives more fun?
The project homepage is the easiest place to get this kind of
text, but don't take that to mean you should just copy it word
for word off SourceForge: their blurb isn't designed to convey
the same information as a package description. So
diverging from upstream isn't an issue here any more than
it's a problem that the man page is different from the FAQ.
Upstream blurbs may involve confusingly divergent specialised
uses of terms like
or (if you're unlucky)
free software, and may be full of
hard-sell advertising copy designed to compete with some
unmentioned proprietary equivalent. Remember that the
interests of our users always take priority over the developer's
ego; stick to an objective summary of the software's pros and
Unless it's going in
Section: (lib)devel, you
should try to avoid
developerese; the typical user only
wants to know what your application is good for, not how it's
implemented. If libeg-bin is part of
EGlib and provides a utility called eg_tool,
don't assume that's self-evident, and make sure that the text
makes sense as a description of libeg-bin. If the
significance of the name isn't obvious, the extended description
is a good place to put an explanation. (If it's a TLA you
may be able to get away with just using the expansion as the
package synopsis.) I'm the kind of user who finds it easier
to get a mental handle on a piece of software if its name has
some intelligible connection to its function, so I often ask
why the name? in d‑l‑e package
reviews. There seem to be quite a few programmers out there
who are content to dub their project
because that's a quick and easy key-sequence to type on a Dvorak
layout, but that label will often be the first aspect of their
brainchild that people encounter as they browse through the
menus. Think of it as the most basic starting point of the
Reimplementations of existing software should be careful not to
live in the past, phrasing their descriptions purely in terms of
how libfoo-tng was an improvement on
libfoo – especially if libfoo2 might
have all the same features. At best, once libfoo-tng
succeeds in becoming the standard implementation and
libfoo vanishes from the repositories, users will be
left relying on software archaeology to work out what purpose
your package serves. And I can never resist pointing out
just how eighties the fad of calling things
Generation is! Beware dated content –
references to boot-floppies or X11R6 support, game reviews assuming
that 3D acceleration is a novelty, and so on. In fact it's a
good idea to avoid claiming that your package is notably
modern (in ten years when it's an orphaned relic that text
will be an annoyance); say what its features are (e.g.
graphical), and let readers make up their own minds about
whether that's an advantage.
Too Much Information:
cross-platformif users are going to want to run the Debian version alongside the Win32 version.
xfoo is a clone of the old Mac OS program macfoo, but avoid saying that xfoo is:
(where you mean
(where you mean
for any distro that wants it)
(where you mean
ported to non-Mac systems)
(where it's unclear what you mean)
designed for HP-UX and occasionally seen on BSDor whether it's
for any commonly used operating system not produced by Microsoft.
The balancing act between too little information and too much is particularly hard for short descriptions. One thing you should usually leave out is the programming language – it might fit in the long description, but it's a waste of space to say that python-pylibpython-mcpython (Section: python) is written in Python. Use debtags!
The Developer's Reference says that package synopses
should be (articleless) noun phrases referring to the
package – that is, they should fit the template
$PACKAGE provides a/the/some $SYNOPSIS (though the
alternative two-part format popular with large families of packages
also has explicit DevRef backing). They should not follow the
example of the man pages that base their description line on verb
$BINARY lets you $DESCRIPTION or
designed to $DESCRIPTION). The logic of standardising on
noun phrases goes like this:
Apologies for the linguistics jargon (which strictly speaking isn't even accurate – I should be talking about N‑bars, not NPs). I advise non-syntacticians just to focus on the template approach.
I suspect my reviews on the mailing list give the impression I'm some sort of nit-picking dimwit, so please bear in mind that the best way of spotting typos, grammatical ambiguities, missing definitions, and so on is to approach the text from the point of view of somebody who doesn't already know what it's trying to say. If you find that sort of ignorance annoying, I apologise; but this may be an indicator that you should delegate the task of writing user documentation to others.
If you disagree with me about some point of grammar or style or whatever, don't worry; at the end of the day, it's the maintainer's decision, not mine, and you're welcome to join the mailing list to provide an alternative viewpoint!
Linux Index | Home Page