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.
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:
MDTK also includes Markdown templates for suggested article formats.
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.
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:
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.
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 certbotThe first part of the command is the
sudocommand. That elevates your privileges, which is just a fancy way to say "make more powerful." Thesnapcommand is a snap package manager. It's a package manager that installs and manages snap packages. The--classicflag tells snap to install the snap package in the classic mode, which means you aren't using strict confinement. Thecertbotcommand 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.
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.
Connect to your server with SSH as a non-root user.
$ ssh myuser@exampleserverInstall 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:
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.
Avoid slang, jargon, jokes, idioms, and metaphors. Instead, focus on the facts, tasks, purpose, and actual user benefit.
MDTK has rules for:
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.
MDTK has US spelling and Latin abbreviation rules.
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:
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.
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.
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.
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.
Documentation must be unambiguous. Use the Oxford Comma to avoid confusion. Compare the following examples:
Consistent use of the Oxford Comma avoids confusion.
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.
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:
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.
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.
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.
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:
These terms often describe the technical process more accurately and avoid the lazy master/slave terminology, which can be inaccurate.
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:
Those words translate more accurately for customers who do not understand English. MDTK has an inclusive language rule.
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:
The second person directly addresses the reader as you and avoids using third-person pronouns such as he, she, his, and hers.
MDTK has a first person rule.
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.
Use a.m. or p.m. preceded by a space.
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.
Use midnight and noon instead of ambigious constructions like 00:00 a.m. or 12:00 p.m.
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.
Define acronyms before the first use. Make sure to leave a space between a definition and an acronym.
Use since to refer to time and because for a reason something happened.
Avoid words like current or phrases like at the time of this writing that imply future changes.
Avoid using Let's, unless referring to Let's Encrypt.
Avoid confusing login with log in. Login is used as a noun or adjective. Log in is a verb phrase.
Avoid confusing setup with set up. Setup is used as a noun or adjective. Set up is a verb phrase.
Once is frequently misused in place of after. Use once when referring to counting. Use after when describing a sequence of events.
Avoid oxymorons such as generally always, mandatory choice, completely obsolescent, and similar phrases.
Avoid using so at the beginning of a sentence.
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:
Vultr prefers plain language over complex phrases. You'll find many examples in the complex substitution MDTK rule, including:
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.
Use a list when describing three or more related items.
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
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.
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.
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.
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.
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
Prefix blockquotes with >, but use them sparingly. Do not use blockquotes as a substitute for code blocks.
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.
To summarize, you should use these resources when writing for Vultr Docs.
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.