Vultr Docs Style Guide

Introduction

Vultr's documentation library contains hundreds of articles written by many authors. Documentation should be clear and easy to understand, without needless slang and jargon. Use this quickstart guide when writing articles for at Vultr. You'll find guidelines for style, formatting, vocabulary, and links to more comprehensive information.

Reference Material

Two excellent (and free!) resources are the Google Technical Writing Course and the Microsoft Style Guide. We highly recommend browsing these resources before planning to write documentation. We have additional resources for authors planning to write documentation for Vultr:

• Vultr Docs Program Guidelines
• Vultr Docs Reference Articles
• Vultr Flavored Markdown Tutorial
• Installation Guide Markdown Template

General Writing Guidelines

Use active voice

In general, write in the active voice, not passive voice. In active voice, the subject of the sentence, usually the user, does the action. In passive voice, the subject of the sentence is the recipient of the action. Words like "was" and "by" are clues that you're writing in passive voice. Active voice instructions are usually shorter and easier to understand. Passive voice is usually less engaging and more complicated than active voice.

• Passive voice: After the software has been installed, the server can be rebooted.
• Active voice: After you install the software, reboot the server.

However, there are some exceptions. In some cases, the active voice is awkward. Passive voice is a better choice when the system performs the action, or the action agent is unknown. Use passive voice if you want to avoid blaming the user for an error.

• Do not use: If the installation fails, you probably made a configuration file error.
• Use this: If the installation fails, the configuration file might have an error.

Use an implied subject for procedure steps

It's common to omit "you" and "you will" in instructional steps. Instructional steps are mostly imperative statements, and it is clear the reader is the subject. When explaining a long serious of steps, use an implied subject to make the article less repetitive.

• Replace this: You will edit the Apache control file.
• With this: Edit the Apache control file.

Sometimes, omitting the subject can disguise the passive voice. A good editing trick to spot passive voice is to finish a sentence with the phrase "by zombies."

• Active voice: (You) edit the Apache control file.
• Passive voice: The Apache control file will be edited (by zombies).

Provide brief detail

Documentation should explain the process and steps. It's insufficient to simply paste a block of code and instruct the reader to run it. However, short sentences and fragments are better suited for documentation than long narratives.

For example, replace this:

The first of the tables that we will create will be the /etc/credentials file. As the name suggests, this will be holding the username and password of each virtual mail account. If you notice from the smtpd configuration file, this is of type passwd. We do this so that OpenSMTPD and Dovecot can share an authentication database and save administration headaches further on down the line.

With this:

OpenSMTPD and Dovecot share the passwd format authentication database /etc/credentials.

It's not unusual to be overly verbose on a first draft. After you've finished a draft, go through the article again and cut unneeded language. Focus on facts, tasks, purpose, and actual user benefits. Avoid advocacy and promotional hype. For clarity, use concise language instead of wordy alternatives that slow the reader. Some expressions such as "it is interesting to note that" add no information and should be eliminated. Wordy phrases, such as these examples, can be shortened.

Suggest reasonable defaults

When faced with a choice, give the reader enough information to make a confident decision, but don't overload them with options. It's not required to explain every possible setting. Give the reader sane defaults for a basic configuration.

Use the Oxford (or serial) comma

Documentation must be unambiguous. Use the Oxford Comma to avoid confusion. Compare the following examples:

• I love my parents, Batman and Wonder Woman.
  Unclear: Their parents are superheroes?

• I love my parents, Batman, and Wonder Woman.
  The meaning is clear: They love their parents, and love Batman, and also love Wonder Woman.

You have the advantage of knowing how your tutorial works. The reader is inexperienced. Consistent use of the Oxford Comma avoids confusion.

Use strong action statements

Avoid weak writing. Avoid "you can", "there is", "there are", "there were." Omit weak modifiers such as "quite," "very," and "extremely." Avoid is starting a sentence with the particularly weak verb constructions "There is" or "There are."

Write conversationally

Prepositions are okay to end sentences with. And another thing. You can start sentences with "And" or "But."

Use grammar check software

Grammar-check software is useful to flag problems to review. MS Word and Grammarly are two popular options.

Formatting and Section Numbers

Break your documentation into logical sections. If the reader will perform installation steps in sequence, use step numbers. Sections that do not depend on a particular order do not need step numbers. Use H2 for major section headers and format them with title case. If you aren't sure about the proper title case for your H2 headings, try the Capitalize My Title tool. Use H3 for subsections with sentence case. Section and sub-sections headings do not use punctuation. Do not include H1 in your Markdown.

An example of proper section headings:

## Introduction and Prerequisites

Lorem ipsum dolor sit amet. The introduction doesn't need a step number. 

## 1. The First Step

Lorem ipsum dolor sit amet...

## 2. The Second Step

Lorem ipsum dolor sit amet...

### Subsections are useful for longer steps

Lorem ipsum dolor sit amet...

### Another subsection

Lorem ipsum dolor sit amet...

## 3. The Third Step

Lorem ipsum dolor sit amet...

## Additional Resources

Lorem ipsum dolor sit amet. Information that isn't part of the step-by-step instructions.

Inline code vs. bold

Use backticks for inline code, like this:

`this is inline code`

Use two asterisks for bold, like this:

**this is bold**

Use inline code sparingly. If you want to emphasize a word, filename, or subdirectory name, use bold.

Code blocks

Use four spaces to create a code block. Code blocks inside bullets or numbered lists require eight spaces. Command lines should be preceded by a prompt. Linux root users should use a hash prompt, standard users use a dollar sign. PowerShell and Windows CMD examples also use appropriate prompts to preface your commands. For example:

A Linux root user performing ls:

# ls

A Linux standard user performing ls:

ls

A PowerShell user performing ls:

PS C:\> ls

A Windows CMD user performing dir.

Note that CMD doesn't leave a space between the prompt and the command, but this space is better for documentation.

C:\> dir

Screenshots

If your article uses screenshots, upload them to a public location, and place the URL in your article. The editors will add your screenshot to our image library. Use JPG or PNG format and avoid animated GIFs.

Summary

Thank you for contributing to our document collection! We aim to be a high-quality resource for the entire Vultr community. If you see an error in our documentation, please use the Suggest an update button included in every Vultr Doc. If you have a question about the Vulr Docs program, please contact us. We appreciate your feedback.