Infobits documentation style guide

Infobits documentation style guide

The Infobits documentation style guide and its source files are licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.


1. Conventions

Infobits documentation conforms to the following conventions:

Convention

Meaning

Example

command

Names of commands, options, sub-commands, paths, files, and URLs display as fixed-width font.

screen, -Dr

replaceable

Replaceable text, such as a file name that a user replaces, displays as fixed width and italics.

file-name

first term

New terms and emphasized text display as italics.

concurrency

user input

Text that a user actively enters displays as bold and fixed width.[a]

At the command line, enter make deploy to publish your changes.

{}

Required syntax elements display within curly brackets.

{-d}

[]

Optional syntax elements display within square brackets.

[-t]

<>

The HTML or XML element (or tag) displays within angle brackets; the name of an HTML or XML element is not in angle brackets.

<body>; the body element

|

A pipe denotes a logical OR within syntax.

a | b

[a] Two verbs that are commonly associated with user input are type and enter.

File names.  For the sake of consistency, and to avoid rendering problems that occur on some platforms and applications, use the following characters when naming a file:

  • lowercase (abc) letters

  • uppercase (ABC) letters only for the initial letter of file names such as Gemfile, Makefile, or Procfile

  • numbers (123)

  • hyphens (-)

  • underscores (_)

  • dots (.)

2. Organization

It is often easier to organize a document after you have ample content. "Let the data do the organizing."

2.1. Chapter versus section

If you chunk information into smaller parts, write an introductory sentence or paragraph. If you find it difficult to write that introduction, your organizational structure might be bloated; you might have a section or subsection that you can remove.

3. Lists

If you use a list, include more than one list item. If you only have one list item, remove the list and rephrase the information using one or two sentences. Doing so removes unnecessary structure. Use only one type of list at a time; avoid * foo: A tool that ..., where * signifies an unordered list and : signifies a definition list.

3.1. Ordered

Use an ordered (or numbered) list for instructions that must be performed in a particular order.

3.2. Unordered

Use an unordered (or bulleted) list for items, or instructions that can be performed in a any order. Put the most important information at the top because that is where readers pay more attention.

3.3. Definition

Use an definition (or variable) list for terms and definitions.

4. Numbers

Generally, single-digit numbers are spelled out. For example, one, two, three, or 10, 11, 12. For details about how to be most clear when writing technical content that includes numbers, see Writing Numbers.

5. Parts of speech

For terms such as set up, setup, and set-up, examine the underlying parts of speech:

VerbNounCompound adjective
set upsetupset-up
log inloginlog-in
log outlogoutlog-out

6. Genderless language

By default, eliminate gendered language in your writing. When in doubt, write directly to your reader. Also, they and them are the preferred pronouns for singular and plural forms if doing so does not cause confusion.

😺

When you download and install the software, it takes approximately three minutes for the installation to complete.

😿

When the user downloads and installs the software, it takes approximately three minutes for him to install it.

Within a single scenario where you need to differentiate between two actors, gendered language is useful. Alice and Bob are common names in such a scenario. For example, Alice emailed Bob at 11:34. and Bob responded with a follow-up message at 11:46.

7. Shortened text

If you have the space to write, use it.

7.1. Acronym

An acronym (or an initialism) is pronounced as a word (or a series of letters), and is a short version of an expanded set of terms. For the sake of simplicity, the term acronym is used in Infobits documentation.

If an acronym is unfamiliar to the reader, expand it first and put the acronym in parentheses as in Simple File Transfer Protocol (SFTP). If an acronym is familiar to the reader, expand it in parentheses after the acronym as in SFTP (Simple File Transfer Protocol).

Note

To avoid insulting your reader, do not expand an acronym if it is used on a regular basis.

7.2. Abbreviation

Expand abbreviations, such as e.g., because they add complexity for non-native readers, are used inconsistently, and are unnecessary.

7.3. Contraction

Expand contractions to remove ambiguity and to increase non-native English speakers' comprehension.

8. Titles

Title styles differ depending on where they are used. To avoid typos, consider using entities, such as See also, for section names that are frequently used. To be consistent, leave out trailing colons within titles if they cannot be inserted systematically.

8.1. Book

For a book, use a title that provides enough context. For example, Infobits documentation style guide clarifies that the style guide is about documentation rather than a programming language, and Infobits specifies that it is derived from Infobits rather than another entity.

8.2. Chapter or section

For a chapter or section, use a title that provides enough context without being redundant. In a chapter titled Lists, for example, use section titles Ordered and Unordered rather than Ordered list and Unordered list.

8.3. Procedure

For a procedure, use a title that starts with a gerund (also known as a verb with an -ing ending), such as Writing in the example that follows. Doing so keeps the procedure name short, and distinguishes the name of a procedure from its steps that start with action verbs.

Procedure 8.1. Writing a procedure

If there are any prerequisites, list them here or provide a link to additional information.

  1. Create a new file (FileNew...).

  2. Write an action verb at the start of each instruction.

    For a list of action words, see Bloom's taxonomy.

  3. Name the file similar to that of the procedure.

    For example, this procedure's file name could be writing-a-procedure.xml.

  4. Separate any additional information from the main instruction.

    For example, previous steps and this one each contain an additional sentence that is not on the same line as the instruction.

A. Documentation quality

To improve the quality and increase the consistency of your documentation, use the following checklist:

Quality checks
Use sentence-style headings.[a] 
Check that your sentences are complete.[b] 
Find any typos within the documentation. 
Find any typos within code examples. 
Proofread your document. 
Eliminate gendered language. 
Eliminate jargon. 
Expand contractions. 
Simplify phrasal verbs. 
Add missing serial commas. 
Replace passive voice with active voice. 
Use parallel structure within titles, lists, sentences, phrases, and names. 
Change extraneous ordered lists to unordered lists.[c] 
Eliminate dangling modifiers. 

[a] Capitalize the first word and any proper noun such as the name of an application.

[b] Begin each sentence with capital letter and end each sentence with a period or colon.

[c] Often, it is tempting to use an ordered list in places where an unordered list is appropriate, such as a list of three platforms on which to install software. Leave it up to the reader to count, and in this example use an unordered list.

Most importantly, be consistent.