6 Language #

Avoid using abbreviations, especially unusual ones. Avoid creating plurals of abbreviations, unless the abbreviation is an acronym or initialism.

Do not artificially limit your audience by excluding or offending members of it.

Avoid indicating gender in your documentation. If possible, use plural to allow use of “they” as the pronoun. Otherwise, use “he or she.”

SUSE supports the Inclusive Naming Initiative which aims to help avoid harmful language. When making language choices for documentation, check the initiative's Evaluation Framework and its “Word lists.”

The SUSE official terminology database, TermWeb, also contains inclusive naming recommendations.

For more information about avoiding gender bias, see The Chicago Manual of Style, 5.43. For information about names of example items, see Chapter 3, Names of example items.

Use commas to separate elements in a series of three or more elements, but do not put a comma before the conjunction in most simple series. For example, “Find basic information about how to register your system, modules and extensions.” Use commas around phrases like for example and that is. Introductory phrases at the beginning of a sentence are normally followed by a comma. For example, “Before using YaST Online Update, configure a network connection.”

Do not use contractions (such as “don't”), unless you are purposefully writing a casual document.

Use en dashes (–) between numbers in a range in tables and figures.

For punctuation, use em dashes (—). Do not surround em dashes with spaces. Use em dashes sparingly.

End sentences in a period. Avoid using exclamation marks. Restrict question marks to question and answer sections.

Under Linux, objects like directories, printers, or flash drives are all considered files. Therefore, the naming and markup conventions are the same for “drives” (for example, hard disks, CD-ROM drives), directories, or files.

The layout for file names and directory names is the same. See the following example:

Most Linux file systems are case-sensitive. Use capitals exactly as they appear in the file system. For more information about markup aspects, see Section 7.20, “References to other external resources” and Section 7.4.2, “File names”.

When it is necessary to refer to file extensions, such as in compound words like “PDF file,” always capitalize the extension.

When writing a descriptive section, use a noun-based heading title, for example, “Concepts of Software.” When writing a task-orientated section, use a verb in gerund, for example, “Installing Software.”

Keep headings short and simple. Do not use both an acronym and the expanded form in a heading. Make sure that headlines in a chapter follow the same pattern.

For advice on how to nest sections, refer to Section 7.15, “Outline levels and sectioning”.

Generally, hyphens are used as joiners for two or more words that form a single concept and function together as a compound modifier before the noun. If the noun comes first, the hyphen is not added. For example, “the list in the upper-left corner” but “place the list in the corner in the upper left.”

There are technical guidelines to help you choose whether to use or not to use a hyphen.

Add the hyphen when:

Do not use the hyphen when:

Many combinations that are hyphenated before a noun are not hyphenated when they occur after a noun. For example: “This is the up-to-date version” and “The calendar is up to date.”

For information about creating lists, see Section 7.13, “Lists”.

Write the integers zero through nine as words. Use numerals for all other numbers.

When the unit of a measurement is abbreviated, always use numerals for the number. In measurements, add a non-breaking space ( ) between the numeral and its corresponding unit abbreviation. Use the % sign when paired with a number, with no space.

For more information, see The Chicago Manual of Style 9.6 and 9.16.

Do not use possessives of acronyms and trademarked terms. Avoid possessives of inanimate objects.

Add a hyphen after the prefix to prefixed words only if you foresee misunderstandings. For example, there is a difference in meaning between “recreate” and “re-create.”

For more information about using hyphens, see Section 6.10, “Hyphens”.

Use quotations to quote from sources, such as books. In all other cases, do not use quotation marks:

To create quotations, use the <quote/> element. This element is easier to localize than hardcoded quotation marks. During processing, localized quotation marks are added automatically. Avoid using single quotation marks.

The period and the comma always go within the quotation marks, as illustrated in Example 6.1, “Quote”. The dash, the semicolon, the colon, the question mark and the exclamation mark go within the quotation marks when they apply to the quoted matter only. They go outside when they apply to the whole sentence.

Avoid using semicolons to join sentences. You may use semicolons in place of commas in very complicated series.

Form clear and direct sentences with 20 words or less. Avoid complicated clauses. Make sure that the relationship between subject, verb, and object is clear. Avoid joining sentences with semicolons. Avoid ending sentences with prepositions.

Avoid using parentheses. Where they are necessary, move them to the end of the sentence. Never nest parentheses.

Always let the reader know the objective of an action before describing the action itself. As an example, write: “To save the settings, click OK.”

Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server.

Use the simple present tense. Apply the simple present tense even to sentences with “if” or “when” clauses and to prerequisites of an action. For example, “If this happens, go there.” or “Glibc is installed.”

Maintain a professional tone. Do not use contractions, except in casual documents. Do not use humor. Be honest and avoid absolutes and exaggerations, but focus on positive aspects.

Use the second person (“you”) to refer to the reader. Normally, the reader is the user or administrator who performs the actions described. For example, “To install all officially released patches that apply to your system, run zypper patch.” Do not overuse “you” and “your.” It is often implied who you are addressing in the instructions. For example, instead of “Install package on your system,” just say “Install package on the system.”

Where possible, use active voice. If there is no emphasis on the object of the verb or if the performer of the action is unknown, use passive voice. “A Samba server must be configured in the network” is an example of the proper use of passive voice. The emphasis is on the server, not on the person configuring it.

When giving a recommendation, start with “We recommend.” Do not use passive phrasings like “It is recommended.”

To refer to other parts of the document, start with “For more information (about), see.”

Most products referenced in the documentation are trademarked. Follow these rules when dealing with these terms:

For more information about markup aspects, see Section 7.17, “Products”.

When referring to labels of user interface items, do not include ending punctuation such as … or :. Whenever possible, refer to user interface items without identifying them as any special type of element. For example, use “click OK” rather than “click the OK button.” However, complex dialogs may require more specific wording.

When referring to UI labels, capitalize them exactly as in the UI itself. Software created at SUSE (such as YaST or Uyuni) should use sentence-style capitalization. If it does not, you can make aware the developers of that software. For more information about sentence-style capitalization, see Section 6.3.1, “Most titles: sentence-style capitalization” and the SUSE Product Brand guide.

For more information about markup for UI labels, see Section 7.22, “User interface items”.