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) [EMAIL PROTECTED] 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 ([EMAIL PROTECTED]), or the [EMAIL PROTECTED] 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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]