Vultr Docs Style Guide

Last Updated: Thu, Sep 9, 2021
Vultr Docs

Introduction

The primary purpose of Vultr's documentation library is to help our international community solve problems. Because many readers use Google Translate to access our articles, you should write them in plain language. Articles written in plain language help readers find, understand, and use the information the first time they read it.

You should:

  • remove details that add little value;
  • use short, simple words and sentences;
  • use active instead of passive voice; and
  • write in a formal but friendly tone.

Get to the Point

Readers use documentation to find the information they need to solve a problem. They seldom read everything you've written, so don't bury important information in dense paragraphs. Instead, make your documentation easy to skim and search.

Please present the most important information first in each section and paragraph. Include any details that help a beginner complete the task, but leave out distracting information, even if you believe it is interesting. Avoid slang, jargon, exclamation marks, humor, idioms, and metaphors. Instead, focus on the facts, tasks, purpose, and actual user benefit. Please avoid advocacy and promotional hype in your documentation.

Edit your Article

Edit your article before submitting it for review. Few writers have the talent to deliver a quality article with the first draft. To edit effectively, you must shift your perspective and assume the role of the reader. The best way to achieve this distance from the article is to set it aside for a day. Later, read it critically, looking for repetition and extra information that will confuse or bore the reader.

Edit the draft ruthlessly with empathy for the reader. Cut every redundant statement or irrelevant fact. A good writer can eliminate one-third of the words from a first draft. A great writer cuts more than half. The majority of articles submitted to Vultr Docs need editing, which reduces the payment we offer. We may reject articles with obvious filler words intended to increase article length. If you submit your article without editing, you may receive a lower payment, delay publication, and harm your reputation.

Use English Grammar

Write documentation in English. Follow the standard grammar and punctuation rules. Many authors use Grammarly, ProWritingAid, or LanguageTool to review articles before submitting them to Vultr Docs.

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 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. For example, 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 the 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

Use bullet points or a numbered list when listing three or more items.

When the sequence doesn't matter, use a bulleted list.

You will require the following items:

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

If the steps must be performed in a specific sequence, use a numbered list.

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

Do not use first, next, finally, or lastly to describe a series of steps, like this:

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 and Images

Use images sparingly in documentation. Screenshots may change often, leaving your article out of date. They are harder to edit than text descriptions. If you use images, make sure your text descriptions are useful for readers that use assistive technology. Provide alternative descriptive text that describes each image for accessibility. Do not depend on images 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.

If your article uses images, 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 move images to our secure server before publishing your article.

More Tips

  • Test your instructions on a new virtual server. The Vultr Docs team will test your article, exactly as written, step-by-step.
  • When writing a guide for an operating system, target a specific version such as Ubuntu 18.04. Targeting an OS family, like Ubuntu, causes frustration when commands go stale over time.
  • When describing everyday tasks such as adding a sudo user, or updating the server, link to one of our reference articles or best practices guides.
  • Please test all hyperlinks. We cannot publish articles with broken hyperlinks.
  • Explain how to locate the latest version of a software package. Avoid linking to a specific version that may be obsolete later.
  • Your article should assume high security whenever possible. If your guide uses HTTP, also include HTTPS instructions. Use a free SSL/TLS certificate from Let's Encrypt at a minimum. If your article uses SSH, use SSH keys instead of passwords.
  • When using example addresses:

Reference Material

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

Thank You

Thank you for contributing to our community library. 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.

Want to contribute?

You could earn up to $600 by adding new articles