Vultr Docs Style Guide

Introduction

To ensure that Vultr's documentation is understandable to an international audience, please follow these style guidelines when writing articles for Vultr.

Write in English

Write documentation in English and follow the standard rules of English grammar. The most common reason we reject articles is because of incorrect spelling, capitalization, and punctuation. Many authors use tools such as Grammarly, ProWritingAid, or LanguageTool to review articles before submitting them to Vultr Docs.

Use Simple Language

Documentation should be clear and easy to understand, without slang, jargon, exclamation marks, humor, idioms, and metaphors, because many readers use Google Translate. Explain the process and steps in enough detail for a beginner, and avoid extraneous commentary. Short sentences are better than long narratives.

After finishing your first draft:

1. Edit the article and cut unneeded language.
2. Focus on facts, tasks, purpose, and actual user benefits.
3. Avoid advocacy and promotional hype.
4. Remove expressions that add no information, such as "it is interesting to note that."
5. Look for places you can replace wordy phrases with concise language.

Write in Second Person

The second person directly addresses the reader as you and avoids using third-person pronouns such as he, she, his, and hers. If you must use the third person, use they and their. Use first-person plural pronouns like we, us, and our with caution, because these usually refer to Vultr. Avoid first-person pronouns like I, me, and my unless writing an FAQ question such as "How to I....?"

Use Consistent Terminology

Avoid multiple variations when referring to the same product, function, or UI elements. Don't ask the user to press Enter in one section, then press Return in another. Make sure to use the correct spelling and capitalization. Look up terms you are unsure how to capitalize, such as WordPress versus Wordpress.

Use Active Voice

In general, write in the active voice, not passive voice. When using the active voice, the sentence's subject, often 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 the passive voice. Active voice instructions are usually shorter and easier to understand. Passive voice is usually less engaging and more complicated than active voice.

However, there are some exceptions. Sometimes 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. For example:

• 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 Present Tense

The readers usually perform tasks in their present, so the present tense is appropriate and more comfortable to read than the past or future tense.

• Replace this: MySQL will prompt you for the password.
• With this: MySQL prompts you for the password.

If you must emphasize that something occurs later (from the reader's perspective), it's okay to use future tense.

Use an Implied Subject

It's common to omit you in instructional steps. Instructional steps are imperative statements where it's clear the reader is the subject. An implied subject makes the article less repetitive.

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

Use the Oxford 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 and superlatives such as quite, very, and extremely. Avoid starting a sentence with weak verb constructions like You can, There is, There are, and There were.

Bullets and Numbered Lists

When listing three or more items, if the sequence does not matter, use bullet points. When describing a series of instructions, use step numbers.

Listing items where the sequence doesn't matter:

You will require the following items:

* Bread
* Apples
* Very small rocks
* Lead
* A duck

A sequence of instructions:

Perform the following steps:

1. Read the program guidelines.
2. Read the style guide.
3. Write an article.
4. Submit the article to Vultr.

Do not use a "first, next, next, finally" style to describe a series of steps. Convert this narrative to a numbered list.

First, read the program guidelines. 
Next, read the style guide.
Next, write an article.
Finally, submit the article to Vultr.

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 begin with a prompt. Linux root users should use a hash prompt, standard users use a dollar sign. PowerShell and Windows examples should use appropriate prompts to preface commands. For example:

A Linux root user performing ls:

# ls

A Linux standard user performing ls:

$ ls

A PowerShell or Windows CMD user performing ls or dir:

PS > ls
C:\> dir

Blockquotes

Prefix blockquotes with >, but use them sparingly. Do not use blockquotes as a substitute for code blocks.

Screenshots

If your article uses screenshots, upload them to a public location and place the URL in your article for the editors to review. Use JPG, PNG, or GIF. For security, your images will not be visible in the Markdown preview. Our editors will download the images and move them to our secure server.

NOTE: If you use images, make sure your descriptions are useful for our customers that use assistive technology such as screen readers. Provide descriptive alternative text that describes each image for accessibility. Do not depend on screenshots to provide information that isn't explained in the text. If possible, do not use screenshots for terminal interactions that can be demonstrated in code blocks.

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 standard reference articles, suitable for linking when describing common tasks.
• Our Vultr Flavored Markdown tutorial is the best reference for Vultr Markdown questions.
• If you use Visual Studio Code to write Markdown, we publish a Markdown Toolkit that can automatically scan your articles for many of these style rules and point out potential problems.
• The Markdown Toolkit includes a suggested Vultr Doc Template.
• Google has a free Technical Writing course that takes most authors about 2 hours to complete.

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.