Skip to content

wug

Jump to bottom
Ornela Marić edited this page May 4, 2023 · 8 revisions

Writing Style and Word Usage Guide

Style

This section contains information about the style and voice conventions we have adopted in SUSE Manager. Having a consistent style help us to create a familiar voice across our documentation suite. This, in turn, helps readers to navigate and understand our documentation.

Sources

As a general rule, follow the SUSE Documentation team Style Guide: https://doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/

For some conventions, we rely on the Chicago Manual of Style: https://www.bookdepository.com/Chicago-Manual-Style-University-Chicago-Press/9780226104201

Language

We use standard US English, with an emphasis on plain (or classical) language. We write in second person ("you"), but avoid using second-person pronouns too much, as they can become tiring to read when over used.

Preference the active voice where possible, but do not be afraid to use the passive voice if it serves a purpose. Always choose the simplest and clearest language, regardless of whether it’s passive or active voice.

Example: Three Ways of Writing One Sentence

  • Natural English: In order to perform X installation process, please ensure that all of the following steps are done:

  • Tech writer’s English: To perform X installation process, verify you have done the subsequent steps:

  • Plain English: To install X, do these steps:

Remember that the order of words is important in English. Put the most important part of a sentence first, this is usually the actor or the action. Use the second part of the sentence to give it a focus: what else should the reader notice?

Readers are often in an agitated state by the time they get to our documentation. Stressed readers jump around in the text, skip words, steps, or paragraphs, and will quickly give up if things seem too complex. To ameliorate this, use short sentences, plain language, and a minimum number of eye-catching details such as admonitions.

Never assume that because you’ve explained something earlier in a document, readers will know it later in the document. You can use cross-references to help guide readers to further information if they need it.

And remember: words mean things.

Grammar

Grammar rules are tacit evolving conventions. They have no implicit value by themselves, they only gain value because everyone is doing it.

There are no hard and fast rules about dangling participles, split infinitives, or ending sentences with prepositions. Obeying these rules can often make language clearer but, in some cases, they make language more complicated. In that case, ignore them.

Accessibility

  • Do not use directional language, like The command below, or The earlier example. This language makes a lot of assumptions: first, that your readers are seeing the document laid out as intended, that the layout has not changed since it was written, and that there isn’t an inconvenient page break in a printed document. Try alternatives like Use this command, or cross-reference to other content.

  • Do not mask URLs, like See the link here. Screen readers will read this as "See the link here", rather than giving the URL. This can also be problematic on printed documents, or in places where internet access is not available. Instead, use See the Example site http://example.com.

Headings

Use title case for all headings:

  • Capitalize the first and last words

  • Capitalize all major words: nouns, pronouns, verbs, adjectives, adverbs

  • Lowercase articles (the, a, an)

  • Lowercase prepositions, unless they are used adverbially or adjectivally

  • Lowercase conjunctions (and, but, for, or, nor)

  • Always lowercase to

  • Always lowercase as

For a complete list of examples, see section 8.158 of the Chicago Manual of Style (16th edition).

Headings should be as simple as possible, and should always be written simple present tense (the action is happening right now). Use declarative noun phrases as much as possible.

For sections that contain a procedure, use the bare infinitive (base) form of the verb followed by the subject. For example: Install SUSE Manager, or Configure the Client.

Procedures

Procedure Titles

Procedure titles should always begin with a gerund. For example, Installing SUSE Manager, or Configuring the Client.

Use present continuous tense for procedure titles (the action is happening now, and will continue into the future).

Process or Procedure

A process contains a number of procedures.

Often, the topic you are writing about will require more than one procedure. In this situation, it can be a good idea to have a process at the top of the section, which lists the procedures contained in the section.

If you do this, ensure that the process uses the same sentence structure as the procedures to reduce confusion.

For example:

To install ``foo``, you will need to:

. Prepare your system
. Install the packages
. Clean up

.Procedure: Preparing Your System

. Step 1
. Step 2

.Procedure: Installing the Packages

. Step 1
. Step 2

.Procedure: Cleaning up

. Step 1
. Step 2

Steps

Every step in a procedure must start with either a verb, or a location.

For example:

  1. Install foo with this command:

or

  1. At the command prompt, install foo with this command:

Ensure that your steps are as atomic as possible. The most important aspect to this is to ensure that the result of an action stays with the action itself.

For example:

  1. Click Save and wait for confirmation.

Results

Result statements are often included as a stand-alone sentence after the procedure, like this:

...
4. Click btn:``Save``.

Now you have a new ``foo``.

If you are working through a procedure called Creating a Foo, then you would expect to have a new foo at the end. In this case, there’s no need to state it.

If you are writing a series of procedures that are part of a larger process, with the result of each procedure flowing into the next, it can be a good idea to explain the transition between each to help orient your reader within the process. For example:

When you have saved your new ``foo``, you can use it to deploy a ``bar``.

.Procedure: Deploying a ``bar``
...

Lists

If a list only has two items, put it in prose. Use numbered lists only if the order is important, otherwise, use bullets. For serial lists, always use an Oxford comma.

Always use a colon after a stem sentence.

For bulleted lists, do not use punctuation at the end of the list items unless each list item is a full sentence. However, if you have one full sentence in a list, put a period at the end of every list item.

Time and Date

How times and dates are expressed can vary greatly between regions. For example, 9/7 can mean either 9 July, or 7 September. To reduce ambiguity, we use a simplified version of the ISO time and date standard, and adhere to the punctuation rules defined in the Chicago Guide.

Examples:

Period Syntax Example

Year

YYYY

2020

Year and month

YYYY-MM

2020-08

Complete date

YYYY-MM-DD

2020-08-13

Date and time (hours and minutes)

YYYY-MM-DD hhmm

2020-08-13 1419

Time (hours and minutes) and a timezone

hhmm TZ

1419 AEST

Time (hours and minutes) and a time offset

hhmm UTC+/-H

1419 UTC+10

If unsure, default to ISO 8601: https://www.iso.org/iso-8601-date-and-time-format.html.

Word Usage

Adverbs

Don’t use. Ever.

And/Or

Do not use. You can usually pick one. If you are not sure, pick and.

Clients and Minions

Use client to mean any client machine. Use Traditional client to mean a pre-3.2 client. Use Salt client to mean a client based on SaltStack. Do not use minion unless you are referring to an internal code element called that, like a minion ID.

Contractions

Do not use.

File system

Two words.

For …​ See

When linking or cross-referencing, use this sentence construction:

For more information on <topic>, see xref:examplebook:topic.adoc[].

Do not use a mask in the cross-reference syntax.

Latin abbreviations

Do not use Latin abbreviations.

Latin abbreviation Use instead

eg

For example

ie

That is

cf

For reference

etc

Avoid if possible, or use and similar

sic

Do not use

ibid.

Do not use

et al.

Do not use

While not an abbreviation, the Latin word via should be avoided where possible. There is usually a more accurate English word, like through, with, or using. Similarly, avoid using the Latin word versus and its abbreviations (vs or v). Choose a phrase like compared to or reword the sentence to be clearer.

Proxy Server

Do not use. Use proxy or SUSE Manager Proxy instead.

While a proxy is technically a proxy server, it is much clearer to have a SUSE Manager Proxy and a SUSE Manager Server as two distinct things.

Upgrade/Update/Migrate

Upgrade: Replace software with a newer (probably major) version of the same software. This will probably involve some downtime, and could take minutes or hours. For example: I upgrade SUMA 3.2 to SUMA 4.0.

Update: Replace software with a newer (probably minor) version of the same software. This will not require downtime, and could take seconds or minutes. For example: I update my clients by using the package manager to check for new versions of installed software.

Migrate: Move data, applications, or software to a new program, platform, or environment. This will require downtime, requires planning, and could take many hours. For example: I migrate the data in my database from MariaDB to PostgreSQL.

Utilize

Do not use. Use use instead.

Verbs

  • Click a button in a graphical user interface using a mouse. Do not Click on.

  • Press a key or key combination on a keyboard

  • Type words or numbers using a keyboard

  • Check a checkbox

  • Uncheck a checkbox

  • Select an item in a menu

  • Deselect an item in a menu

  • Navigate to a page or location in a graphical user interface

Will

Avoid where possible. The word will usually indicates that you are writing in future tense, rather than present tense. Instead of When you click the [Save] button, a dialog will appear, use Click the [save] button, a dialog appears, or Click [Save] to see the dialog.

uyuni logo

Uyuni Docs

Clone this wiki locally