Author: David Finster
Last Updated: Thu, Sep 9, 2021The 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:
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. You should include details that help a beginner complete the task, but leave out distracting information, even if you believe it is interesting.
Avoid slang, jargon, jokes, idioms, and metaphors. Instead, focus on the facts, tasks, purpose, and actual user benefit. Please avoid advocacy and promotional hype in your documentation. Exclamation points rarely have a purpose in documentation and should be avoided.
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. 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 used to increase the article length for a higher payment.
Please use our Markdown template when writing your article.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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
Prefix blockquotes with >, but use them sparingly. Do not use blockquotes as a substitute for code blocks.
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.
We highly recommend browsing these resources before submitting an article for review.
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.