Overall Design

Design standard

This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups.

Here's what you'll find here:

  1. Titles

  2. Overview

  3. Heading styles

  4. Documenting the User Interface

  5. Abbreviations, acronyms, initialisms, and special characters

  6. Using version numbers correctly

  7. Using admonitions

  8. Making recommendations

1 Titles

When applicable, the title should be a combination of the complete product name and its version. For example, "<A Software> 6.xxx.xxx Installation Guide", or "<Another Software> 23.xxx.xxx User Manual".

2 Overview

This has to be the first paragraph of every article where we give an overview of what the readers will learn in the article, in one or two lines.

3 Heading styles

This section covers various aspects of heading styles and design

3.1 Capitalization

The standard for all the documentation is:

  • Title case the titles.

  • For the heading, the title case is only for the first letter. For the others, use lower cases (see this document as a reference), apart from exceptions. If we're writing a paragraph that talks about the UI, write "Documenting elements of the User Interface".

3.2 Writing effective titles

Use a title that represents the content.

Typically, the "ing" form of a verb is a good way to title larger chunks of content such as chapters and sections, for example "Creating Branches".

Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging".

Activities and subtasks that the user should perform can alternatively use an imperative verb for clarity.

Imperative verbs are prescriptive, such as "Create" or "Delete". Example: "Assess the Health of an OpenShift Cluster".

In some cases, a verb might not be appropriate because the content is purely informational. Instead of using a vague verb like "Understanding", "Describing", "Introducing", or "Exploring", either use a more specific verb, or use a noun phrase instead of a verb.

A noun phrase is descriptive and omits a verb, for example "Installation Overview" or "The OpenShift Web Console."

Example

Improvement

Understanding OpenShift Users and Groups

OpenShift Users and Groups

Introducing Cluster Updates

Cluster Updates

3.3 File Names, Commands, and Related Terms

When creating chapter and section titles, do not include file, command, or similar names, and do not include markup elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds.

4 Documenting the User Interface

This section shows the standard way to document UI elements.

4.1 Navigating through multiple UI options:

Use "Navigate to" when moving through multiple UI options because it covers all cases where you might have to click, point to, press, select, or otherwise make a series of selections to start an action.

4.2 Figures, illustrations, and screen captures

The following specific conventions apply to using captions and callouts with figures in technical documentation and are generally recommended.

  • If the image is well documented and described in the surrounding text, no caption or callouts are required.

  • If the image is not fully described in the surrounding text, use a caption or legend to complete the information for the reader.

  • If the image is complex and requires a detailed explanation, consider using callouts to describe each of the relevant parts.

4.3 Documenting command terminology and syntax

Sufficient variation exists in the terminology that is used to describe commands, options, arguments, and so on that only general advice is provided here.

When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses.

When referring to commands or syntax specifically used in Linux machines or in Bash, use the symbol $ to indicate that is.

So, for example:

$ cd my_path

Refers to a command on a Linux machine.

When an action must be performed by the superuser, this must be declared. For example:

$ sudo apt-get update

4.4 Documenting multiple or long commands

Sometimes you need to show how to use long commands that extend over two or more lines, or that include several commands in a single example. If the commands are relatively short and straightforward, then include the commands on consecutive lines:

$ cd Documents
$ vi myFile.txt

If the commands are long, complex, or wrap over multiple lines, then use the following design:

  1. Change the name of the logstash key-file:

$ sudo mv my_very_long_path/logstash.key my_very_long_path/logstash.key_old

4.5 Referring to replaceable paths

To refer to a path that users need to replace with something that is specific to their system, use the appropriate markup for your content, the correct syntax for the system and object in question, and an indicative name. Use a leading slash if the absolute path is required.⁠

Example: referring to replaceable paths on Linux systems:

"Mount the ISO file in /path/to/iso/file."

Remember to use the appropriate syntax for the system that you are documenting or describing.⁠

Example: referring to replaceable paths on Microsoft Windows systems:

"Mount the ISO file in C:\path\to\iso\file."

5 Abbreviations, acronyms, initialisms, and special characters

This section defines abbreviations, acronyms, initialisms, and special characters.

⁠Abbreviations

An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation.⁠

Acronyms

An acronym is a word that is formed from the initial letters of a name, such as ROM for Read-Only Memory, or by combining initial letters or part of a series of words, such as LILO for Linux Loader. COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol.⁠

Initialisms

An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol.⁠

Special Characters

For the purposes of this guide, special characters refer to those characters that are listed in Section "Contractions and abbreviations", at point 5, in the Grammar section.

This section addresses how to use special characters as part of a file or directory name, such as "the .bashrc file" and "the _build/ directory".

5.1 Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly

This section describes how to use abbreviations, acronyms, initialisms, and special characters correctly in the documentation.⁠

5.1.1 First Mentions

Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ...". Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML.⁠

5.1.2 Capitalization

Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled-out version. For example, "central processing unit (CPU)".⁠

5.1.3 Articles

When deciding which articles to use, consider pronunciation. For example, use "an RTS (real-time strategy)", because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade", because RAM is an acronym and you pronounce it as a word (răm).

5.1.4 Plurals

To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe. For example: ROMs, PINs, BIOSes.⁠

5.1.5 Possessives

Don't use possessives with abbreviations.⁠

5.1.6 Special characters

Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.

If a file or directory name begins with a special character, such as an underscore, then you need to pronounce that character.

For example, using "an _build/ directory" is correct, because you pronounce "an underscore build directory".Using "a -compile/ directory" is correct, because you pronounce "a dash compile directory".

6 Using version numbers correctly

The preferred format for product names includes only the major version number. For example:

  • <A product> 6

  • <Another product> 23

When writing about a product line, product release, or product family, use major version numbers. It includes all the releases (past, present, and future) of that major version.

Only use minor version numbers when you are referring to a specific minor release, or to a feature that is specific to that minor release. For example:

  • <A product> 6.3.10 was released in June 2023.

Major changes usually take place in major version releases, and are carried through any minor updates to that release. If you are referring to a major change, or to the first appearance of a new technology, it is therefore most accurate to refer to the major release.

Avoid using the "dot-oh" release number. For example, don't use <A product> 6.0. Use instead <A product> 6.

7 Using admonitions

To call attention to a statement, use an admonition. This technical documentation currently uses Noteand Warning admonitions.

Depending on the tools and workflow, admonitions might automatically include a suitable title according to the type of admonition. Do not use a phrase or anything else for the title. Keep the following considerations in mind if using admonitions:

  • Keep statements brief and to the point.

  • Use admonitions sparingly so that they do not lose their effectiveness.

  • Use a Note admonition to bring extra information to the user's attention.

  • Use a Warning admonition to alert the reader to potential changes, such as files being removed, and not to perform the operation unless fully aware of the consequences.

Example of usage:

NOTE: you may also need to read the following documentation.

WARNING: this OS version is not supported anymore.

8 Making recommendations

When making a recommendation, the preferred verbiage is "<This company> recommends ..." instead of the common but indirect "It is recommended ...". Recommendations can include best practices, recommended practices, and product-specific suggestions. ⁠

Example (incorrect)

"Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project."

"It is recommended to generate a service account for each microservice in your project."⁠

Example (correct)

"Although the attack surface is reduced to the same-project traffic, <this company> recommends creating multiple service accounts within a project."

"<This company> recommends that you generate a service account for each microservice in your project."

PreviousGrammar

Last updated