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:
Capitalize the first and the last word.
Write articles in lowercase. Articles are: the, a, and an.
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.
Write certain conjunctions in lowercase: and, but, for, nor, and or.
Write as and to in lowercase.
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:
For computer input, computer output and user interface elements, use different markup. See also Section 7.4, “Command-line input and command-line output”, Section 7.22, “User interface items”, and Section 8.1, “Using DocBook tags”.
Use
<emphasis/>
to call attention to new words or phrases, for example, “using so-called target units,” to use words in a non-standard way, for example, “packages can get in an orphaned state,” and to refer to a word or term itself, for example, “The word processor came into use around 1910.”Do not use quotation marks to indicate irony. Avoid irony in technical writing. See also Section 6.20, “Tone and voice”.
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.
“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 ” .
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
” rather than “click the
” 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”.