Article

Table of Contents
Try Vultr Today with

$50 Free on Us!

Want to contribute?

You could earn up to $300 by adding new articles!

Vultr Docs Style Guide

Last Updated: Fri, May 8, 2020
Vultr Docs

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. Just as programmers need reference material when writing software, authors need guidelines for style, formatting, and vocabulary. This quick start guide is a short reference with 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.

Formatting

Break your documentation into logical sections. Use H2 for major section headers, and preface your H2 sections with step numbers (use numerals, not words) and colons as shown. Use title case for H2 headings. We prefer titles formatted according to the Chicago Manual of Style. If you aren't sure about your title format, try the Capitalize My Title tool.

Use subsections for minor sub-steps

Each major H2 section may also contain multiple subsections. Use H3 for subsections, and format them in sentence case. Subsections usually don't have punctuation.

Writing Tips

Use active voice

Active voice instructions are usually shorter and easier to understand.

  • Active voice: Compile the script.
  • Passive voice: The script needs to be compiled.

Shorter is better

Documentation is not a blog post. Short sentences and fragments are better suited for documentation than long narratives. At the same time, documentation should explain the steps. It's insufficient to simply paste a block of code and instruct the reader to run it.

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.

Suggest good 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 an implied subject

It's common to omit "you" and "you will" in instructional steps. It's implied that the reader is "you".

  • Replace this: You will compile the script.
  • With this: Compile the script.

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.

Avoid first-person narratives

Scan your documentation for the words "I" and "we". Vultr's documentation is a collection of articles written by many authors. There are no individual credits. Likewise, "we" could refer to the author and the reader working together, or it could refer to Vultr. Unless the context of "we" is clear, you should avoid these pronouns.

  • Replace this: I recommend the free "Let's Encrypt" SSL certificate for Apache.
  • With this: Use the free "Let's Encrypt" SSL certificate for Apache.

Use strong action statements

Avoid weak writing. Most statements should start with a verb. Avoid "you can", "there is", "there are", "there were".

  • Replace this: You can access Vultr servers from any device, and you get automatic backups and DDOS protection.
  • With this: Get automatic backups, DDOS protection, and access Vultr servers from any device.

Use grammar check software

Grammar-check software isn't perfect, but it it's useful to flag problems to review. MS Word and Grammarly are two popular options.

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 at the bottom of every Vultr Doc. If you have a question about the Vulr Docs program, please contact us. We appreciate your feedback.

Want to contribute?

You could earn up to $300 by adding new articles