| Style Guide for SUSE Program Texts | ||
|---|---|---|
 | ||
| Style Guide for SUSE Program Texts | ||
|---|---|---|
| | ||
Table of Contents
Abstract
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 Section 2, “Rules for Specific Situations”.
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 Section 4, “Resources”.
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 Section 4, “Resources”). 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
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.
| | ||
| 2. Rules for Specific Situations |