0.991 2005-11-02 Release Candidate 3 This style guide applies to all programs produced by SUSE. This is primarily YaST and SaX. It covers the rules and guidelines for writing and editing the original English program texts. Additionally, some tips are included to help translators of these texts. Apply rules when they make sense. Exceptions can occur, but be prepared to defend your decision. If you are unsure, ask others on the team for their opinions. Write so it can be read and understood by nonnative speakers. It is quite possible for users to select English instead of their native language. This also makes it easier for bug testers to use the program before translations are complete. Do not divide texts into multiple strings. Not all languages work the same, so split strings are often a problem for translators. It also makes it more difficult to ensure consistency and clarity in the proofreading process. Do not use contractions, such as don't or can't. This is done for consistency with the manuals and to maintain a professional style. Also avoid slang and idioms. When working on texts that apply to a group of similar items, such as radio buttons, write all the items in a similar way. If one item has a verb at the beginning, the others should as well. This similarity in structure is called parallelism. For example, the following items are parallel: CUPS Printer IPX Network Server Other Setup Allow room for text expansion in GUI design. Many languages require more words or characters to express something than English does. There are two systems of capitalization used in program strings. When to use which system is included in the rules for different situations in . When capitalizing, do not change the capitalization of filenames, configuration variables, and similar case-sensitive items. These should be presented in the case required by the system to avoid confusion. Title-style capitalization is, unfortunately, quite complicated. Just do your best to follow these simplified rules. The rest will be cleaned up in the proofreading process. Capitalize the first word no matter what it is Capitalize all major words Lowercase the, an, a, and, but, for, or, nor, to, and as Lowercase prepositions, such as up, in, down, and of Capitalize the last word The following are some examples of YaST strings in title-style capitalization. Hostname and Name Server Configuration Do Not Use LDAP Reload All Patches from Server The specific rule followed in the proofreading process is the Chicago Manual of Style rule 8.167. It is also described in both the SUSE and Novell style guides. See . Capitalize the first word. Only capitalize other words if they are proper nouns or names. Do not use spaces before commas (,), periods (.), colons (:), or semicolons (;). Avoid using exclamation marks at all. The wording and the type of message provide the needed emphasis. Avoid using punctuation dashes, called em dashes. If it cannot be avoided, use --. Only use / if it is part of a standard term, such as TCP/IP. Usually or or and should be used where a / is used. Use American English as the original language for all texts. Many words have multiple "acceptable" spellings, but it has been necessary for SUSE and Novell to standardize on certain variants for consistency. The following list is an excerpt of the more extensive lists in the SUSE and Novell Style guides (see ). Use the first variant in Webster's dictionary as the standard spelling for anything not on these lists. 3D back-end back up (verb) backup (noun) boot disk boot loader cannot case-sensitive, case-insensitive certificate authority client/server command line e-mail filename file system front-end GNOME hard disk hostname hotplug, hotplugging, hotpluggable Internet intranet journaling local host (normal), localhost (default name of the local host) log file log in (verb), login (noun) log out (verb), logout(noun) mount point pathname RAM disk reconfigure re-create runlevel runtime set up (verb), setup (noun) stand-alone start-up uninstall username Web Web page Web server X Window System (do not shorten to X Windows) It is impossible to make an exact guideline for the maximum length of strings. The appearance should be checked in the UI in both ncurses and Qt. A basic guideline is that strings that do not wrap themselves have a maximum length of 78 characters. Using only 54 characters is a nicer length for pop-up dialogs. Give modules short noun names. Use title-style capitalization. Examples of good module names are: DNS Server LDAP Client Security Settings This includes dialog titles, frame labels, and pop-up titles. Keep the text short and concise. Do not use ending punctuation (: or .). Use sentence-style capitalization. Do not use any ending punctuation. Do not use multiple sentences. The status bar texts for the Control Center currently appear in the desktop files after GenericName=. These rules apply to all input and command widgets. These widgets include check boxes, buttons, radio buttons, and text entry fields. Keep the labels short and concise. Use a label like Name instead of Enter Name or Select Name. Ending punctuation, such as : or ., should not be used. Use ... at the end of command widgets that open a pop-up or new dialog requiring user input. Do not use ... on navigational buttons, such as Next or Back. Do not use a space before it. For example, Detailed Configuration.... The final button of a wizard should always be Accept. These rules apply when you giving the user information about the current status of a selection or service. This means it is also used for summaries and proposals. For example: Packages to Update: 4 The category of the information should be title-style (Packages to Update:) because it works like a header. End the category in a colon (:). The information itself should be sentence-style. Keep status information shorter than a sentence and do not end it in a period (.). Label progress bars with a short noun phrase in title-style capitalization. The text should be informative. Examples: Patch Download Package Installation When the process is already described, as in the progress stages of initialization, do not label the progress bar. rwalter: add shots Progress stages appear in situations like module initialization. They tell the user what YaST does in order. Write them like a to-do list using sentence-style capitalization. Do not use any ending punctuation on the stages. Examples of good progress stages include: Read configuration files Save configuration Use these when showing that YaST is currently doing something and the user needs to wait. Write a phrase using a verb ending in -ing because the thing is currently being done. End it in ... to show that it is an ongoing operation. Use sentence-style capitalization. Examples of appropriate busy messages include: Reading package information... Writing configuration file... Error messages should give the user only as much information as is useful. Do not confuse the average user with overly technical error messages. For errors that can be resolved by an experienced user, provide the technical information with a Details... button. Errors related to program bugs should have the detailed information placed in the log and not marked for translation. Use the text "Internal error occurred. See the logs for information." as the error message. Use sentence style capitalization. End in a . if it is a complete sentence or more than one sentence. rwalter: need standard text for bug errors Use sentence-style capitalization for warnings. End in a period (.) if it is a complete sentence or more than one sentence. Confirmation messages should clearly describe the situation to confirm. Use complete sentences or multiple sentences and end each sentence with a period (.). The last sentence should be a clear question that can only be answered with the available options. Clear questions for yes-no confirmations include: Really abort? Use this password? Use title-style capitalization for column and row headers. Use sentence-style capitalization for entries. Do not use ending punctuation. Use title-style capitalization for all tree items. Help needs to give the user clear directions on how to use the dialog. Also provide information about specific user input that is required, such as IP addresses, domain names, or text in a restricted character set. Start the help with a concise paragraph describing what the dialog is all about. It should let the reader know why he would use this dialog. If it works for your dialog, orient the help towards tasks the user may want to perform. If the layout is complex, describe the elements of the dialog. If the dialog only addresses a single task, as in the dialogs for editing configuration values, focus on the elements of the dialog. Provide background information if it is likely to be needed by the average user. Headings should be placed in big and b tags and capitalized title-style. All help texts should have a heading at the top. In many cases, additional headings are unneeded. The texts should be written in paragraphs (p tags) using complete sentences. Do not use br to force line breaks. If possible, have two or more sentences per paragraph. This is not, however, always reasonable in help texts. Place widget labels in b tags. Use tt for example values and URLs. Because the tags are very attention-grabbing, avoid overusing them. If you want to use the widget labels like headers when making UI-based help, place the label in b tags and follow it with a colon (:). See . <p><b>IP Address</b>: Enter the IP address of the host, such as <tt>10.1.1.100</tt>.</p> <p><b>Hostname</b>: Enter the hostname for the host, such as <tt>earth</tt>.</p> The command line interface has its own rules. For command line help texts, use sentence-style capitalization. Do not use ending punctuation except in rare cases when multiple sentences are used. When multiple sentences are used, end all sentences in a period (.). Headers, summary headers, and similar items should be written title-style and end in a colon (:). Table headers should not have colons but should be capitalized title-style. SUSE program texts are translated to a number of languages. Because of this, it is very important to make program texts translator-friendly. It is unlikely for the translators to have access to the newest program. All they have is the information provided by the po files. Different languages require different structures and orders. Splitting a text into multiple strings causes problems and confusion for translators and proofreaders. Never split strings. It must be possible for translators to change the order of variables. The Qt-style numbered variables make this possible. Include comments for translators whenever a string might be unclear to the translator. One-word strings can be confusing if the word can have multiple meanings or be different parts of speech. For these, provide a comment describing the meaning or context of the string. When a string includes a variable, provide a comment explaining what will replace the variable in the final string. Also provide comments for macros other than &product;. For the YaST to-do list-like lists of what YaST does in order or similar items, mark them progress stages. Provide an appropriate comment for translators when a string should be limited to a certain length. Never translate the macro &product;. It is replaced with the name of the product on which YaST is run. This can be SUSE Linux, Novell Linux Desktop, or any other product. "Progress stages" are to-do list like-items that display the steps a program will take. Translate these consistently for your language. Do not translate any string or part of a string that comments specify should not be translated. This is done rarely. If something is not clear, ask. Although the developers do their best to explain things, they may not realize that something is not clear. Unless otherwise marked in comments, strings that do not include HTML-like markup are limited to 78 characters. Error messages, warnings, and other pop-ups should be limited to 54 as much as possible. When necessary, create additional line breaks with \n. The following are resources that can be useful when writing program texts. SUSE Documentation Style Guide Novell Documentation Style Guide Online version of Merriam-Webster's Dictionary. It is easily searchable. Chicago Manual of Style, 15th Edition This is the source of the capitalization rules. It also contains a lot of other useful information.