-
Notifications
You must be signed in to change notification settings - Fork 98
wug
Lana Brindley v1.0, 2019-08-23
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.
As a general rule, follow the SUSE Documentation team Style Guide: https://doc.opensuse.org/products/opensuse/Styleguide/opensuse_documentation_styleguide_sd/
We also rely heavily on the IBM Style Guide: https://www.bookdepository.com/IBM-Style-Guide-Jana-Jenkins/9780132101301
For some conventions, we rely on the Chicago Manual of Style: https://www.bookdepository.com/Chicago-Manual-Style-University-Chicago-Press/9780226104201
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.
We rely on the American Heritage Dictionary: https://www.bookdepository.com/American-Heritage-Dictionary-Houghton-Mifflin-Company/9780553583229
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.
-
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 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.
-
Do not use directional language, like
The command below
, orThe 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 likeUse 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, useSee the Example site http://example.com.
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
.
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).
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
Every step in a procedure must start with either a verb, or a location.
For example:
-
Install
foo
with this command:
or
-
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:
-
Click Save and wait for confirmation.
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`` ...
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.
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.
Don’t use. Ever.
Do not use.
You can usually pick one.
If you are not sure, pick and
.
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.
Do not use.
Two words.
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.
Do not use Latin abbreviations.
Latin abbreviation | Use instead |
---|---|
eg |
|
ie |
|
cf |
|
etc |
Avoid if possible, or use |
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.
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: 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.
Do not use.
Use use
instead.
-
Click
a button in a graphical user interface using a mouse. Do notClick 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
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](https://github.com/uyuni-project/uyuni-docs/wiki/images/uyuni-logo.png)