Guidelines for style and language use in debconf templates
The SmithReviewProject has developed a number of guidelines for use of language and style in debconf templates during its work. They are recorded here partly to aid maintainers when writing templates, and partly for a checklist that can be used by the reviewers.
It should be noted that English style and language varies greatly, and there is no body that draws up a list or rules that should be followed. This is especially true of technical writing where many of the conventions are still being created. English is also a very idiosyncratic language, and so some parts of it may seem a little strange or illogical.
If you would like to discus any of these items, or you would like advice on use of English in Debian packaging or elsewhere in the project please contact the debian-l10n-english team at firstname.lastname@example.org.
Please mention - This is rather informal, and does not have quite the right meaning for a debconf template, please use Please enter instead.
en_US vs en_GB - The Smith reviews standardized on en_US, preferrably
Quotation marks - while there was no concensus reached on one set of marks to use, templates should be consistent within a package. You can use either pairs of " marks, or pairs of ' marks, alternating where nesting is needed.
Command names - Where a command name is included in the text it should be kept in the same case as the command itself. If the command name starts a sentence there are 3 suggested ways to handle it
- Leave it in the original case. This violates the "capital letter to start a sentence" rule, but is more in line with technical usage.
- Quote the program name. This makes it clear it is intentional. This could also be done in the rest of the text, but it is not normally done.
- Rework the sentence. One trick that often works is to start the sentence "The whatever command".
Version abbreviation - When saying "version 3" it is commonly abbreviated to "v3" it is preferred to have the "v" as lower case, with no space before the number. This is not necessary though, and if the usage in that package is commonly different, and it is most recognisable with a different style, then be consistent with that.
Short paragraphs - paragraphs longer than a few lines (4-5) tend to be hard to read and may be overread. It is suggested to shortent them down and separate different ideas on different paragraphs.
Debconf templates length - Debconf templates should fit on one 80x25 screen with the (most common) dialog interface. As this is usually hard to measure, it is recommended to shorten templates as much as possible (remember that English is very concise and that translations have to fit as well)
- English typography requires wide spaces after so-called "full stops" (final dots in sentences) just like many other Latin-based languages. However, it seems that several native speakers use to type two spaces to render this in computer texts. Indeed, nothing is normalizing this practice. As a consequence, many texts have a varying spacing method. In the Smith project, it is proposed to avoid such double spaces and stick with single spaces, leaving up to rendering engines to use the correct typography.
Speakers of some languages make some common mistakes when using the English language. Some of them are listed here to try and help you to avoid them. The list should be kept to things that are clearly wrong, rather than style issues, and should only included those things that appear to be common due to differences in particular languages.
Allow to VERB - English does not use the construction "allow to VERB", instead it uses either "allows VERBing" or "allows SOMETHING to VERB", for instance
- "allow to enter text" would become "allows entering text" or "allows the user to enter text".
- Reworking or extending the sentence to avoid either of the previous two constructions can often lead to a more pleasing sentence, however how to do that is not so easy to explain.