7 Language #

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

Do not omit articles to make a sentence shorter. Write “Edit the /etc/hosts file.” instead of “Edit file /etc/hosts.” Omitted articles are hard to translate and can make a noun string ambiguous.

Do not use an article before a noun that is followed by an identifier. The identifier makes the noun specific already. Write “See step 3” instead of “See the step 3.”

In a series of items, the position of the article changes the meaning. In “Restart the new services, timers and sockets,” all three are new. In “Restart the new services, the timers and the sockets,” only the services are new. Repeat the article before every item when the modifier applies to the first item only.

Do not use an article before a product name.

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 4, Names of example items.

Capitalize the first word after a colon only if it is a proper noun or the start of a complete sentence. For example: “Error message: The system could not connect to the server.” But: “Server roles: file server, Web server and database server.”

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

You may use common contractions (such as “don’t,” “it’s” or “we’ll”) to make your writing more natural and conversational. Contractions improve readability and engagement by reflecting how people speak. Be consistent: do not mix a contraction (for example, “can’t”) with its fully spelled form (“cannot”) in the same 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 8.17, “References to other external resources” and Section 8.3.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 8.14, “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.”

Do not use jargon, slang or regional expressions. Many of our readers do not have English as a first language, and such terms are hard to translate and easy to misunderstand. Use a plain technical term instead:

Do not use humor, irony or cultural references, such as references to films, sports or holidays. They rarely translate and can exclude readers. For more information, see Section 7.3, “Biases and inclusiveness”.

A technical term is not jargon. Terms such as container, inode or snapshot are correct in the right context. If a term is new to the intended audience, define it at first use.

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

A multi-word noun is a noun that is modified by other nouns, such as “cluster node configuration file”. Strings of nouns are ambiguous, because the reader cannot see which word modifies which. Use a maximum of three words in a multi-word noun, including the final noun.

To shorten a longer noun string, use one of the following methods:

This rule does not apply to names that you must not change, such as product names, command names or user interface labels. Do not shorten or hyphenate them.

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.

Start each paragraph with a topic sentence that states what the paragraph is about. Use the sentences that follow to explain that topic or to add information about it. If you read only the first sentence of every paragraph in a section, you should get a correct outline of the section.

Give each paragraph one topic. When you start to describe a second topic, start a new paragraph.

Do not write more than six sentences in a paragraph. A longer paragraph usually contains more than one topic. Split it into two paragraphs and give each of them a topic sentence.

Short paragraphs with a single topic also help the systems that process our content. Search engines and AI assistants split a page into chunks, and a paragraph that covers one topic stays meaningful when it is retrieved on its own. For more information, see Chapter 6, Writing for the Web.

A phrasal verb is a verb with a preposition or an adverb, such as “to shut down”. Do not use a phrasal verb if a precise single-word verb exists. Phrasal verbs often have several meanings, which makes them ambiguous and hard to translate:

Some phrasal verbs are the established technical term for an action, and no single-word verb replaces them. Use them as they are listed in Appendix A, Terminology and general vocabulary, for example, “to log in to,” “to set up,” “to shut down” and “to back up.” Do not replace them with a single-word verb.

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 7.12, “Hyphens”.

Use a pronoun only if the noun that it replaces is unambiguous. If a sentence contains more than one noun that the pronoun can refer to, repeat the noun instead.

Do not start a sentence with “this,” “that,” “these” or “it” to refer to the whole of the previous sentence. Name the thing that you refer to. Write “The service reads the file at start-up. This behavior prevents changes at runtime.” instead of “The service reads the file at start-up. This prevents changes at runtime.”

Do not use “it” as an empty subject in a technical statement. Write “The installation takes approximately 10 minutes.” instead of “It takes approximately 10 minutes to install.”

For information about gender and pronouns, see Section 7.3, “Biases and inclusiveness”.

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

The period and the comma always go within the quotation marks, as illustrated in Example 7.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. 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.

Keep sentences within the following limits:

Write one instruction in a step. Use the imperative form: write “Enter the user name.” instead of “The user name should be entered.” Describe two actions in the same step only if the actions occur at the same time, or if a result follows immediately from the action. For example, a command and the output that the command returns belong in the same step.

Do not combine “must” with an imperative. Write “Before you remove the disk, unmount the file system.” instead of “Before you remove the disk, you must unmount the file system.” An exception is a safety-critical instruction, where “must” can show the reader that the instruction is important.

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. Do not add spaces on either side of a forward slash.

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

Use one term for one thing, and use that term every time you refer to that thing. Do not use synonyms for variety. If you write “cluster node,” do not switch to “cluster member” or “machine” later in the document. A reader who sees a different term assumes that you describe a different thing.

In the same way, do not use one term for two things. If “host” means the physical machine, do not also use it for a host name entry.

For approved terms, see Appendix A, Terminology and general vocabulary and the SUSE official terminology database, TermWeb. If a term is not listed, choose one spelling and apply it consistently in the document. You can also suggest missing terms using the feedback form in TermWeb.

Use the same phrasing for actions that recur. For example, always write “Confirm with OK.” or always write “Click OK.”—do not alternate between them. Consistent phrasing lets translation memory reuse existing translations and keeps the translated documentation consistent.

Maintain a professional tone that is helpful and honest. Do not use humor, and avoid absolutes or exaggerations; instead, focus on positive aspects and factual accuracy. Contractions are permitted to keep the writing engaging and conversational.

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:

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 7.4.1, “Most titles: sentence-style capitalization”.

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

Do not use a product name, a command name or a user interface label as a verb. Write “Use rsync to copy the directory.” instead of “Rsync the directory.” Names are nouns, and a reader who does not know the name cannot see which action you describe.

Use a verb to describe an action. Do not turn the action into a noun. Write “Before you remove the disk, unmount the file system.” instead of “Before the removal of the disk, perform an unmount of the file system.” A verb makes the sentence shorter and shows who performs the action.

Keep the conjunction “that” after verbs such as “make sure,” “note,” and “verify.” Write “Make sure that the service is running.” instead of “Make sure the service is running.” Without “that,” the reader can first read the following noun as the object of the verb.

For information about tense, see Section 7.26, “Tense”. For information about active and passive voice, see Section 7.28, “Tone and voice”. For information about phrasal verbs, see Section 7.18, “Phrasal verbs”.