To ensure that Vultr's documentation is understandable to an international audience, please follow these style guidelines when writing articles for Vultr.
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.
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:
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....?"
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.
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:
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.
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.
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
A Linux standard user performing
A PowerShell or Windows CMD user performing
PS > ls C:\> dir
Prefix blockquotes with >, but use them sparingly. Do not use blockquotes as a substitute for code blocks.
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.
We highly recommend browsing these resources before submitting an article for review.
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.