Vultr Docs Style Guide

Last Updated: Tue, Apr 5, 2022
Vultr Docs

Introduction

Welcome to the Vultr Style Guide. If you are a Vultr Docs author, this guide is for you. You'll find links to templates, the Markdown toolkit (MDTK), and learn how to write with our preferred style, formatting, and terminology. You'll also find tips to make your article sail through the review process and earn the highest payments possible.

Vultr Markdown Toolkit (MDTK)

The Vultr Markdown Toolkit (MDTK), which is open-source and available for download on GitHub, has a set of custom Vale linting checks for many of the rules in this Style Guide. In addition, MDTK has a custom spell-check dictionary and a recommended set of Visual Studio Code extensions, plus a .code-workspace that sets all the preferred defaults for Vultr Docs authors.

The MDTK styles are compatible with Vale Server and Vale CLI, so you can use them in any of these environments:

  • Visual Studio Code
  • Atom
  • Sublime Text
  • Google Docs
  • Chrome

MDTK also includes Markdown templates for suggested article formats.

Other Editing Tools

We update MDTK frequently and encourage authors to use MDTK to lint their articles before submission. However, MDTK is not a substitute for a human editor and does not perform complete grammar checking. Many authors use tools like Grammarly, ProWritingAid, Hemingway App, or LanguageTool to review their articles before submitting them to Vultr Docs.

And, of course, none of these tools are a substitute for a human editor. You should always carefully proofread your articles before submitting them to Vultr Docs. Follow the standard English grammar and punctuation rules.

Use Plain Language

The primary purpose of Vultr's documentation library is to help our international community solve problems. Because many of Vultr's customers use online translation tools to read 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:

  • Use short, simple words and sentences
  • Use active instead of passive voice
  • Write in the second person
  • Use a formal but friendly tone
  • Remove details that add little value

Make your documentation easy to skim and search. You should include all the required information but remove distractions. Present the most important information first in each section. Include details that help a beginner complete the task but leave out distracting information, even if you believe it is interesting.

Compare these examples to the plain language version below.

Too Verbose

The first thing you need to do is open a terminal on your machine. After you open the terminal, use the SSH command to connect to your server. Make sure you don't connect as the "root" user because that's dangerous. Instead, you should use your username. It will take a few seconds. Now, when you are connected, type out these commands. I'll explain what they do in a minute.

   $ sudo snap install --classic certbot

The first part of the command is the sudo command. That elevates your privileges, which is just a fancy way to say "make more powerful." The snap command is a snap package manager. It's a package manager that installs and manages snap packages. The --classic flag tells snap to install the snap package in the classic mode, which means you aren't using strict confinement. The certbot command is a snap package that installs and manages the Let's Encrypt certificate. You'll use that later in the article. Certbot is a free, open source software tool for automatically using Let's Encrypt certificates on manually-administrated websites to enable HTTPS. Certbot is made by the Electronic Frontier Foundation (EFF), a 501(c)3 nonprofit based in San Francisco, CA, that defends digital privacy, free speech, and innovation.

This version is too verbose. It forces the reader to pick out the critical information from the surrounding unimportant details. They might be interesting details, but they don't help the reader perform the task.

Too Brief

Connect to the server and run:

   $ sudo snap install --classic certbot

This version is too brief. It leaves out important information and doesn't explain what the command does.

A Plain Language Version

  1. Connect to your server with SSH as a non-root user.

       $ ssh myuser@exampleserver
    
  2. Install Certbot with Snap. Certbot requires the --classic flag.

       $ sudo snap install --classic certbot
    

This version is plain language. It has all the information required without overloading the reader with unimportant details.

If you'd like to learn more about plain language, see these sites for more information:

Promotional Hype

Please avoid advocacy and promotional hype in your documentation. For example, you should avoid language like this:

FoobarDB version 12 is armed to the teeth with amazing features that will blow your mind.

That might be better stated as:

FoobarDB version 12 supports high availability with hot standby and failover.

Slang, Jokes, and Metaphors

Avoid slang, jargon, jokes, idioms, and metaphors. Instead, focus on the facts, tasks, purpose, and actual user benefit.

MDTK has rules for:

Edit Your Article

Most importantly, edit your article before submitting it for review. Unfortunately, few writers have the talent to deliver a quality article with the first draft.

You must shift your perspective and assume the reader's role to edit effectively. 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 confuse or bore 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.

If you don't edit your work, you may receive a lower payment, delay publication, and harm your reputation. We do not publish articles with obvious filler designed to increase the article length for a higher payment.

Use English and US Spelling

  • Use the US spelling for words that vary by locale. For example:
    • Use license, not licence
    • Use synchronize, not synchronise
    • Use behavior, not behaviour
    • Use color, not colour
  • Avoid non-English words or phrases, such as de facto or ad hoc.
  • Avoid Latin abbreviations for common English phrases:
    • Use for example, not e.g.
    • Use that is, not i.e.
    • Use and so on, not etc. or et cetera

MDTK has US spelling and Latin abbreviation rules.

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 sentence's subject 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. MDTK has a passive voice rule.

However, there are some exceptions where active voice is awkward. Passive voice is better when the system performs the action, or the action agent is unknown. You can also use passive voice 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 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 There is, There are, and There were. MDTK has a weak writing rule.

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. MDTK has a future tense rule.

Use an Implied Subject

It's common to omit you in instructional steps. Instructional steps are imperative statements where it's clear that 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.
    • The meaning is unclear. Are their parents are superheroes?
  • I love my parents, Batman, and Wonder Woman.
    • The meaning is clear. They love their parents, Batman, and also Wonder Woman.

Consistent use of the Oxford Comma avoids confusion.

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.

Capitalization

Look up terms you are unsure how to capitalize, such as WordPress versus Wordpress. When starting a sentence with a product name, command, or trademark that is normally lowercase, Vultr follows the Wikipedia Manual of Style for Trademarks. Here are some examples:

Correct Capitalization

  • Rsync transfers files and folders that have changed recently. You can copy your files with the rsync command.
  • Cron is a task scheduler. You can schedule tasks with cron to run at specific times.
  • iCloud is a cloud service. You can use iCloud to store your files.

Wrong Capitalization

  • rsync transfers files and folders that have changed recently. You can copy your files with the rsync command.
  • cron is a task scheduler. You can schedule tasks with cron to run at specific times.
  • ICloud is a cloud service. You can use iCloud to store your files.

Search Engine Optimization

Avoid "Click Here" for Links

When writing documentation, you should avoid "click here" for links. Instead, the link should describe itself. This helps the reader and improves Search Engine Optimization (SEO). For example, avoid this:

[Click here](https://example.com/example-doc) to learn how to install a Marketplace app.

Instead, write that link as:

Learn how to [install a Marketplace app](https://example.com/example-doc/).

Another common SEO mistake in documentation is to use the word here as the link instead of describing where the link points. You should avoid this:

Download the latest version [here](https://www.example.com/download/).

Instead, write that link as:

Download the latest version [at the official Marketplace website](https://example.com/download/).

Descriptive links are easier to read and search engine-friendly. They also help the reader understand the context of the link. MDTK has a meaningful links rule.

Inclusive Language

Avoid Simply

Simply is subjective and alienating. It's not a word that describes the task but a word that presumes the reader's skill level. How do you know if a task is simple for the user? Simply is lazy and unimaginative; many other words could do the job better. It's filler text that pads out your writing, and you should remove it. MDTK has a simply rule.

Avoid Congratulations!

Exclamation marks rarely have a valid use in technical documentation, and adding "Congratulations! You have just..." to the end of your article is a lazy filler line that adds no value. It's not helpful to the reader who completed the tutorial successfully, and it's infuriating to a reader who found an error in your article or had trouble following your steps. Instead, you should add links to more resources. MDTK has an exclamation rule.

About Master and Slave

Vultr documentation should follow the upstream project's terminology. For example, if the project uses primary and replica, don't refer to the systems as master and slave. Be mindful that some projects may change their terminology. Before writing your tutorial, you should check the latest documentation to ensure your terms agree with the project's preferred language. If there is no upstream project guidance to follow, use terms that communicate the technical principles accurately. For example:

  • Primary
  • Source
  • Leader
  • Secondary
  • Replica
  • Follower

These terms often describe the technical process more accurately and avoid the lazy master/slave terminology, which can be inaccurate.

About Whitelist and Blacklist

Vultr's customers are global, and not all cultures automatically assume that white means good or that black means bad. Often, whitelist and blacklist don't communicate the technical principles accurately. When writing for Vultr Docs, you should follow the upstream project's documentation terminology. In the absence of upstream project guidance, use accurate technical terms that translate well with online translation tools. For example:

  • Allow List
  • Safe List
  • Deny List
  • Block List

Those words translate more accurately for customers who do not understand English. MDTK has an inclusive language rule.

Bias-free Communication

Use gender-neutral alternatives for common terms. In generic references, don't use he, him, his, she, her, or hers. Instead, you should use one of these constructions:

  • Rewrite in the second person (you).
  • Rewrite using a plural noun and pronoun.
  • Use the or a instead of a pronoun ("the cloud server" instead of "her cloud server").
  • Refer to a person's role (reader or customer for example).
  • Use person or individual.
  • It's okay to use the plural pronouns they, their, or them to refer to a single person.
  • Don't use constructions like he/she and s/he.

MDTK has a gender rule.

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 in Vultr Docs.

MDTK has a first person rule.

Other Style Preferences

Vultr has several other preferred style guidelines that you should follow. You'll find corresponding MDTK rules for many of these preferences. We highly recommend that you consider using MDTK to ensure your documentation is consistent with the rest of the community.

Date Formatting

Use a.m. or p.m. preceded by a space.

  • Correct: The server reboots at 11:52 a.m. each Tuesday.
  • Avoid: The server reboots at 11:52 AM each Tuesday.

When using a.m. and p.m., avoid redundant phrases like in the morning. The abbreviations a.m. and p.m. always refer to a time before and after noon.

  • Avoid: The server rebooted at 3:00 a.m. in the morning.

Use midnight and noon instead of ambigious constructions like 00:00 a.m. or 12:00 p.m.

  • Correct: The scheduler cleared the cache at noon.

Punctuation

Avoid exclamation points at the end of sentences. They are not appropriate in technical documentation.

Avoid ellipsis...

Use one space after a period between sentences.

Preferred Language

Define acronyms before the first use. Make sure to leave a space between a definition and an acronym.

  • Correct: Deploy your Vultr Kubernetes Engine (VKE) cluster in the customer portal.
  • Avoid: Deploy a Vultr Kubernetes Engine(VKE).

Use since to refer to time and because for a reason something happened.

  • Correct: It's been an hour since he left because he had a flat tire.
  • Avoid: He is late since he had a flat tire.

Avoid words like current or phrases like at the time of this writing that imply future changes.

  • Correct: Use the most recent version of VKE when following this guide.
  • Avoid: The current version of VKE is 1.20 at the time of this writing.

Avoid using Let's, unless referring to Let's Encrypt.

  • Correct: Let's Encrypt is a free service that issues SSL/TLS certificates.
  • Avoid: Let's log in to the server with SSH.

Avoid confusing login with log in. Login is used as a noun or adjective. Log in is a verb phrase.

  • Correct: Log in to the server with SSH.
  • Correct: Navigate to the login screen.
  • Avoid: Login to the server with SSH.

Avoid confusing setup with set up. Setup is used as a noun or adjective. Set up is a verb phrase.

  • Correct: Set up Nginx server.
  • Correct: Edit the installation setup script.
  • Avoid: Setup Nginx server.

Once is frequently misused in place of after. Use once when referring to counting. Use after when describing a sequence of events.

  • Correct: The server reboots once per day.
  • Correct: The server reboots after each update.
  • Avoid: Once the server reboots, run the update.

Avoid oxymorons such as generally always, mandatory choice, completely obsolescent, and similar phrases.

Avoid using so at the beginning of a sentence.

  • Avoid: So, let's log in to the server with SSH.

Avoid modifiers like very, absolutely, and extremely to incomparable terms like true, false, impossible, and unavoidable. Here are a few common examples you should avoid:

  • extremely unavoidable
  • absolutely false
  • very final
  • increasingly impossible

Vultr prefers plain language over complex phrases. You'll find many examples in the complex substitution MDTK rule, including:

  • Replace a number of with many
  • Replace all of a sudden with suddenly
  • Replace an adequate number of with enough
  • Replace because of the fact that with because
  • Replace carry out an evaluation of with evaluate

Formatting

Vultr Docs use a consistent Markdown style for headings, bullets, ordered lists, and other elements. If you are new to Vultr Docs, we recommend using a Markdown template as a starting place for your article.

Lists

Use a list when describing three or more related items.

Unordered Lists

When presenting a list where the sequence doesn't matter, use an unordered list. Vultr prefers asterisks as the list marker rather than hyphens. For example, the order you gather these items does not matter:

Please gather the following items:

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

Ordered List

If the reader must perform steps in a particular sequence, use an ordered list. Vultr prefers to always use 1. as the list marker. This format allows you to move, add, and delete items without renumbering. The Markdown engine increments the numbers for you when displaying the article. For example, these steps should be performed in this sequence:

1. Read the program guidelines.
1. Read the style guide.
1. Request an assignment.
1. Write the article.

The MDTK .code-workspace file has preselected these lists preferences for you.

Narrative Form

Do not use the first, next, finally, or lastly narrative form 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.

We reject articles that use this narrative form when an ordered list is more appropriate. MDTK has a first-next rule. Don't use adverb forms of steps like firstly, secondly, thirdly, or lastly. Please rewrite the sentence.

Inline Code

Use backticks for inline code, like this:

`this is inline code`

Use inline code sparingly because it makes the text harder to read and follow. Use bold or italic text unless you describe a literal command or filename. Use a code block when possible instead of inline code.

Code Blocks

  • Use four spaces to create a code block.
  • Code blocks inside lists require eight spaces.

Command Lines

Command lines should begin with a prompt. This makes it easier to identify the command line and its arguments. It also prevents the reader from accidentally copying the entire line and submitting it as a command without reviewing or editing it.

  • Linux root examples use a hash prompt.
  • Linux standard examples use a dollar sign.
  • PowerShell and Windows CMD examples should use appropriate prompts.
  • Databases and application shells should use appropriate prompts.

For example:

A root user performing ls on Linux:

# ls

A standard user performing ls on Linux:

$ ls

A PowerShell user:

PS> ls

A CMD user:

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 the documentation. Screenshots may often change, leaving your article out of date. In addition, they are more complicated to edit than text descriptions. If you use images, make sure your text descriptions are helpful for assistive technology readers. Provide alternative descriptive text that describes each image for accessibility. Do not depend on pictures to provide information that isn't explained in the text. If possible, do not use screenshots for terminal interactions that could be shown as text.

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

  • Deploy a new cloud server at Vultr and test your article before submitting it for review.
  • 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

To summarize, you should use these resources when writing for Vultr Docs.

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. Also, 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.

Die deutsche Version dieser Website ist eine Übersetzung, die nur zu Informationszwecken erstellt wurde. Die englische Version hat Vorrang.