Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Documentation Style Guide / Language
Applies to 2024-10

6 Language

We write documentation in American English. Where spelling differences exist between American and British English, use the American English variant. For verbs ending in either -ise or -ize (like localise/localize), use the -ize variant.

When in doubt about the spelling or usage of a word, first see Appendix A, Terminology and general vocabulary. If the usage of a word is not regulated there, use the preferred spelling from https://www.merriam-webster.com/ (https://www.m-w.com/ for short).

The correct spelling of SUSE product names is listed in the terminology table (Appendix A, Terminology and general vocabulary) and in the entities file of the Doc Kit repository at https://github.com/openSUSE/doc-kit/blob/main/entities/generic-entities.ent. If a product name is not listed in either spot, refer to the official SUSE Products page and the Marketing department. Make sure to not use articles in front of product names.

When in doubt about a style rule, see The Chicago Manual of Style, 15th Edition.

6.1 Abbreviations

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

6.1.1 Acronyms

Introduce acronyms by providing the expansion in parentheses after the acronym. Sometimes chapters and parts are used across multiple documents. Therefore, provide the expansion of an acronym at least once per chapter.

However, do not use headlines to introduce an acronym. Headlines or captions must not contain both an acronym and its expansion. If a term is commonly written as an acronym, use the acronym in the title. When mentioning the term for the first time in the following text, use its expanded form. All following occurrences of the term in this chapter should then use the acronym.

Create plural forms of acronyms by adding a lowercase s. For example, use CDs and BIOSes. Never add an apostrophe before the s or es.

For clarity, avoid using possessive forms of acronyms. For example, do not use XMLʼs specification.

6.1.2 Latin abbreviations

Do not use Latin abbreviations. Use the full English form: for example, use that is instead of i.e.. As an exception to this rule, the abbreviation etc. is allowed.

6.1.3 Units of measurement

You may use abbreviations of common units of measurement. For more information about units of measurement, see Section 6.12, “Numbers and measurements”.

6.2 Biases and inclusiveness

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.

6.3 Capitalization of headings and titles

6.3.1 Most titles: sentence-style capitalization

Sentence-style capitalization is the most common capitalization used in SUSE documentation. When using sentence-style capitalization, only proper nouns and the first letter of the first word of a phrase are capitalized. Apply sentence-style capitalization to all running text and all types of headings and titles that are part of the document content. An example for sentence-style capitalization is Ceph core components.

6.3.2 Document titles: title-style capitalization

For document titles, such as book, article, and set titles, use title-style capitalization. This capitalization style is explained in The Chicago Manual of Style, 8.167. A simplified version of these rules is below:

  1. Capitalize the first and the last word.

  2. Write articles in lowercase. Articles are: the, a, and an.

  3. Write prepositions in lowercase unless they are used with a verb (Logging In) or in a noun (The On Button). Prepositions are, for example: up, in, of, through, and between.

  4. Write certain conjunctions in lowercase: and, but, for, nor, and or.

  5. Write as and to in lowercase.

  6. Capitalize everything that is not mentioned above.

Examples for title-style capitalization are Deployment Guide (book title) or Kernel Module Packages for SUSE-Based Distributions (article title).

6.4 Commas

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.

6.5 Contractions

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

6.6 Dashes

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.

6.7 End of sentence punctuation

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

6.8 File and directory names

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:

  • In general, use forward slashes (/) to separate nested directory or file names. If you are describing actions performed on Windows* systems and within a Windows-native file system, use backward slashes (\) instead.

  • In general, when giving absolute paths, always start with a leading slash to indicate the root of the file system. If you are describing actions performed on Windows systems and within a Windows-native file system, do not add a leading slash to absolute paths.

  • When referencing a directory name, add a trailing slash. This helps distinguish between directory names (for example, /etc/YaST2/) and file names (for example, /etc/YaST2/control.xml). For less experienced Linux users, it might be helpful to specify in the running text if it is a file, device, or directory. For example: In the /etc/hosts/ directory, do the following.

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.

6.9 Headings

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”.

6.10 Hyphens

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:

  • The last letter of the prefix and the first letter of the word are the same (shell-like). However, double-e combinations usually do not get a hyphen: preempted, reelected.

  • The words begin with the prefixes self-, ex- (that is, former), and all-: self-assigned, ex-service, all-data.

Do not use the hyphen when:

  • The prefix and the following word start with a consonant (subpackage).

  • The two-word phrase includes the adverb very and all adverbs ending in -ly: a very good time, an easily remembered rule.

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.

6.11 Lists

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

6.12 Numbers and measurements

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.

6.13 Possessives

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

6.14 Prefixes

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”.

6.15 Quotations

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.

Example 6.1: Quote

Suds may froth, the sign reads.

6.16 Semicolons

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

6.17 Sentence structure

Form clear and direct sentences with 25 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.

6.18 Slashes

Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server. Do not add spaces on either side of a forward slash.

6.19 Tense

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.

6.20 Tone and voice

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.

6.21 Trademarks

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

  • Never use trademarks in headings.

  • Only use the ®, ™ or ℠ marks for SUSE products.

  • Use an * (asterisk) for all service marks or trademarks of third-party companies. This acknowledges the service mark or trademark of the other company. It also protects SUSE if the protection of the brand changes in any way.

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

6.22 User interface items

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”.