Debconf Templates Style Guide
During the recent months, I have been mostly involved in the work of
translation debconf templates to french.
During this work, I very often found templates which seemd to be
inconsistent with some unwritten (or written, but in several documents
or mailing lists messages) rules.
This often lead me to mail exchanges with package maintainers,
sometimes involving Joey Hess as debconf author, sometimes involving
debian-l10n-english mailing list contributors and so on.
It rapidly became evident that some formalisation of debconf tempaltes
writing rules and recommendations could probably help package
maintainers to write debconf templates which could easily be
recognised as "well-written".
Some general style harmonisation could also greatly improve the
perception of our distribution, giving it a more "professionnal"
aspect.
Below is the current state of this document. I throw it in the wild,
being prepared to whatever flame it may generate..
Why the list crosspost ?
-debian-boot because there is a specific part about debian-installer
-debian-l10n-english because this is probably the place in Debian
lists for gettingsome wise input about the Proper Way to write Good
English
-debian-devel because I like being flamed....^W^W^W^W^W...because
I want to reach as many DD's as possible
Please comment....and remember that this document is far from being
finished... :)
Up to now, thanks to Joey Hess and Denis Barbier for their initial
proofreading.
Debconf Templates Style Guide
-----------------------------
1. Do not abuse debconf
-----------------------
Since debconf appeared in Debian, it has been widely abused and
several criticisms received by the Debian distribution come from
debconf abuse with the need of answering a wide bunch of questions
before getting any little thing installed.
Keep usage notes to what they belong: the NEWS.Debian, or
README.Debian file. Only use notes for important notes which may
directly affect the package usability. Remember that notes will always
block the install until confirmed or bother the user by email.
Carefully choose the questions priorities in maintainer scripts. See
man debconf-devel(7) for details about priorities. Most questions
should use medium and low priorities.
2. General recommendations for authors and translators
------------------------------------------------------
2.1 Write correct English
-------------------------
Most Debian package maintainers are not native English speakers. So,
writing properly phrased templates may not be easy for them.
Please use (and abuse) debian-l10n-english@lists.debian.org mailing
list. Have your templates proofread.
Badly written templates give a poor image of your package, of your
work...or even of Debian itself.
Avoid technical jargon as much as possible. If some terms sound common
to you, they may be impossible to understand for others. If you cannot
avoid them, try to explain them (use the extended description). When
doing so, try to balance between verbosity and simplicity.
2.2 Be kind to translators
--------------------------
Debconf templates may be translated. Debconf, along with its sister
package po-debconf offers a simple framework for getting
templates translated by translation teams or even individuals.
Please use gettext-based templates. Install po-debconf on your
development system and read its documentation ("man po-debconf" is a
good start).
Avoid changing templates too often. Changing templates text induces
more work to translators which will get their translation "fuzzied". If
you plan changes to your original templates, please contact
translators. Most active translators are very reactive and getting
their work included along with your modified templates will save you
additional uploads. If you use gettext-based templates, the
translator's name and e-mail addresses are mentioned in the po files
headers ('egrep "Last-Translator" debian/po/*.po').
If in doubt, you may also contact the translation team for a given
language (debian-l10n-xxxxx@lists.debian.org), or the
debian-i18n@lists.debian.org mailing list.
2.3 Do not make assumptions about interfaces
--------------------------------------------
Templates text should not make reference to widgets belonging to some
debconf interfaces. Sentences like "I you answer Yes..." have no
meaning for users of graphical interfaces which use checkboxes for
boolean questions.
More generally speaking, try to avoid referring to user actions. Just
give facts.
3. Templates fields
-------------------
This part gives some information which is mostly taken from the
debconf-devel(7) manual page.
3.1 Type
--------
<to be written>
3.2 Description: short and extended description
------------------------------------------------
Templates descriptions have two parts: short and extended. The short
description is in the "Description:" line of the template.
The short description should be kept short (50 characters or so) so that it
may be accomodated by most debconf interfaces. Keeping it short also
helps translators as most languages are less compact than English.
The short description should be able to stand on his own. Some
interfaces do not show the long description by default, or only if the
user explicitely asks for it or even do not show it at all. Avoid
things like "What do you want to do?"
The short description does not necessarily have to be a full
sentence. This is part of the "keep it short and efficient"
recommendation.
The extended description should not repeat the short description. If
you can't think up a long description, then first, think some more.
Post to debian-devel. Ask for help. Take a writing class! That
extended description is important. If after all that you still can't
come up with anything, leave it blank.
The extended description should use complete sentences. Paragraphs
should be kept short for improving readability. Do not mix two ideas
in the same paragraph but rather use another paragraph.
Don't be too verbose. Some debconf interfaces cannot deal very well
with decriptions of more than about 20 lines, so try to keep it below
this limit.
For specific rules depending on templates type (string, boolean,
etc.), please read below.
3.3 Choices
-----------
<to be written>
3.4 Default
-----------
<to be written>
4. General rules depending on templates type
---------------------------------------------
4.1 Boolean templates
---------------------
- The short description should be phrased in the form of a question
which should be kept short and should generally end with a question
mark. Telegraphic style is permitted and even encouraged if the
question is rather long (remember that English is compact while
other languages are often less compact)
- The extended description should NOT include a question.
- Again, please avoid referring to specific interface widgets. A common
mistake for such templates is "if you answer Yes"-type
constructions.
4.2 String/password templates
-----------------------------
- The short description is a prompt and NOT a title. Avoid
question style prompts ("IP Address?") in favour of
"opened" prompts ("IP address").
The use of colons is recommended.
- The extended description completes the short description. No question
here and always phrases. Telegraphic style should be prohibited.
4.3 Notes
---------
- The short description should be considered to be a *title*.
- The extended description is what will be displayed as a more detailed
explanation of the note. Phrases, no telegraphic style.
- DO NOT ABUSE DEBCONF. Notes are the most common way to abuse
debconf. As written in debconf-devel manual page: it's best to use them
only for warning about very serious problems.
4.2 Select/Multiselect
----------------------
- The short description is a prompt and NOT a title. Do NOT use useless
"Please choose..." constructions. Users are intelligent enough...:)
- The extended description will complete the short description and may
mention the choice. I may also mention that several choices can be done
for multiselect templates (though the interface often makes this
evident)
5. Specific rules
-----------------
5.1 Debian installer
--------------------
Entries for main menu should use the infinitive form: "Execute a
shell" instead of "Shell execution". They are of type "text".
They (and their translations) should not exceed 58 characters length.
Error templates should use the "error" template type.
Templates should not refer directly to other debian-installer modules
main menu entry name. These entry names are likely to change. For instance, do not use:
Go back to "Partition a hard disk" and retry
but rather
Go back to the hard disk partitioning step and retry
Reply to: