Vultr Docs Style Guide

Introduction

Vultr's documentation library contains hundreds of articles written by many authors. To maintain consistency and quality, please use this style guide when writing articles for Vultr. You'll find guidelines for style, formatting, vocabulary, and links to more comprehensive information.

Reference Material

We highly recommend browsing these resources before submitting an article for review.

• The Vultr Docs program guidelines for more information about our rules, payments, and acceptable topics.
• Our library of common reference articles, suitable for linking when describing common tasks.
• Our Vultr Flavored Markdown tutorial is the best reference for Markdown questions.
• Our Markdown template is a starting place for style and organization.
• The Google Technical Writing Course is free, and it's a good refresher even for experienced writers.
• The Microsoft Style Guide is extensive and agrees with our editorial style.

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" in instructional steps. Instructional steps are mostly imperative statements where it's clear the reader is the subject. An implied subject makes the article less repetitive.

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

Provide brief detail

Documentation should be clear and easy to understand, without needless slang and jargon. Explain the process and steps in sufficient detail for a beginner, but avoid extraneous commentary. Short sentences are better than long narratives, particularly for our customers that use Google Translate to read the documentation.

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 authentication database /etc/credentials. The database is in passwd format.

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. Some expressions such as "it is interesting to note that" add no information and should be eliminated. Use concise language instead of wordy alternatives. For example:

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.

Consistent use of the Oxford Comma avoids confusion.

Use strong action statements

Avoid weak writing. Avoid weak modifiers such as "quite," "very," and "extremely." Avoid starting a sentence with weak verb constructions like "You can", "There is", "There are", and "There were."

Use grammar check software

Grammar-check software is a useful tool. Microsoft Word and Grammarly are 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. Reserve it for commands or filenames.

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:

By default, CMD doesn't leave a space between the prompt and the command, but it makes copy/paste easier for the reader.

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.

Emojis

Restrained use of emojis can enhance an article, but it's rare to use more than one or two per article. Less is more.

These emojis are approved.

📝 Note: Lorem ipsum dolor sit amet...
👉 Important: Lorem ipsum dolor sit amet...
🤚 Attention: Lorem ipsum dolor sit amet...
🛑 Warning: Lorem ipsum dolor sit amet...

These emojis are approved, but easy to abuse. Please use them sparingly.

🎉 Congratulations
⌛ Wait
❓ Question

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 Vultr Docs program, please contact us. We appreciate your feedback.