Vultr Docs Style Guide

<?xml encoding="utf-8" ??>

Introduction

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

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. For example, exclamation points rarely have a purpose in the documentation and should be avoided.

Edit Your Article

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 will confuse or bore the reader. Finally, 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 Our Markdown Template

Please use our Markdown template when writing your article.

Use English Grammar

Write documentation in English. Follow the standard grammar and punctuation rules. Many authors use Grammarly, ProWritingAid, Hemingway App, or LanguageTool to review articles before submitting them to Vultr Docs. Vultr publishes Vale styles in our Markdown Toolkit that work with the Visual Studio Code Vale extension.

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.

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

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.

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 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 Inclusive Language

Avoid Simply

"Simply" is subjective and alienating because it implies a task should be easier than it is. 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 should be removed.

Avoid Congratulations!

Exclamation marks rarely have a valid use in technical documentation, and adding "Congratulations! You have ..." to the end of your article is lazy filler. 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 indicate the tutorial has completed and provide links to more resources. For example:

This concludes the tutorial. If you'd like to learn more, see the product-name documentation.

Master/Slave

Vultr documentation should follow the upstream project's terminology. For example, if the project uses "primary" and "replica," don't refer to them as "master" and "slave." Be mindful that some projects may change their terminology. Therefore, you should check the latest documentation before writing your tutorial 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 actual technical process more accurately and avoid the lazy "master/slave" terminology which can be inaccurate.

Whitelist/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 work well with Google Translate. For example:

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

Those words will translate more accurately for customers who do not understand English.

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.

We reject articles that use this narrative form when a numbered list is more appropriate.

Formatting Tips

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

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

• 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:

  • Use the RFC 5737 example IPv4 address blocks: 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24.
  • Use the RFC 3849 example IPv6 address blocks: 2001:0db8::/32.
  • Use the RFC 6761 example domains: example.com, example.net, example.org, or anydomain.example.
  • Use the RFC 7042 example MAC addresses: 00-00-5E-00-53-00 through 00-00-5E-00-53-FF.
  • Use the RFC 5398 example Autonomous System (AS) Numbers: 64496–64511 and 65536–65551.

Reference Material

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

• Please use the Vultr Docs Template when planning your article.
• If you use Visual Studio Code to write Markdown, we publish a Markdown Toolkit that can automatically scan your articles for many of these style rules and point out potential problems.
• The Vultr Docs program guidelines for more information about our rules, payments, and acceptable topics.
• The Vultr Flavored Markdown tutorial is the best reference for Vultr Markdown questions.
• Google has a free Technical Writing course that takes most authors about 2 hours to complete.
• The Purdue University Online Writing Lab (OWL) is an excellent writer's resource.

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.