Vultr Docs Creator Guide

Author: David Finster

Last Updated: Wed, Dec 7, 2022
Vultr Docs

Introduction

Welcome, Vultr Creators! We are thrilled you've decided to help expand our documentation library. The primary purpose of our documentation library is to give our international community of developers information that helps them develop solutions on Vultr's global infrastructure.

To ensure that articles about our products and services are consistent and high-quality, we ask that you read and follow this style guide. Following these standards ensures that your articles earn the highest payment possible and move swiftly through our review process.

How to Request Assignments

  1. Important: Log in to Vultr so your assignment request is linked to your account.

  2. Choose a title from our Creator Assignment Dashboard or suggest your own idea.

  3. Make your assignment request through the Request Article form. Please include a link to the assignment. Make sure we've approved your assignment before you begin writing. We may add suggestions or have questions before we assign it to you.

  4. We will notify you in a Vultr support ticket when your assignment is ready.

How to Submit Assignments

  1. Write your article in Vultr-flavored Markdown.

  2. Important: Edit your article! We don't accept articles that require extensive editing by our team.

  3. Important: Test your article by performing all the steps yourself before you submit it for review. We do not accept articles with technical errors.

  4. Upload your article to us through the article submission form.

  5. We will review your article and provide status reports via the ticket system at each step.

  6. We will send you a payment proposal if we approve the article.

  7. If you accept, we will publish your article after verifying that you've been paid.

Program Rules

  • You must link a payment method to your Vultr account to be eligible for assignments. See the FAQ below for more details.

  • You must request an assignment before submitting articles to Vultr Docs.

  • Articles must be in English, with proper spelling and grammar. See our style guide for more information.

  • You must submit original content that no one, including yourself, has previously published. Vultr has a zero-tolerance policy for plagiarism, including self-plagiarism.

  • Articles published by Vultr are exclusive to Vultr Docs. Do not publish the article elsewhere without written permission from Vultr.

  • We may reuse the content as needed or rewrite it to improve readability.

  • At your request, we may publish your name as the article's author. We might decline to give you credit if the article requires extensive editing by our team.

  • Do not mention other providers that offer similar services to Vultr.

  • Use a minimum number of URL links to resources outside Vultr Docs.

  • Violations of any program rules may lead to suspension from the Docs program and disqualify your future submissions.

We do not accept articles about:

  • Blockchain and cryptocurrencies

  • Peer-to-peer sharing guides for programs such as BitTorrent

  • Anonymous surfing guides for programs such as Tor, Shadowsocks, SOCKS5, or other proxy software

  • How to bypass or "crack" licensing systems of applications

  • Products primarily used to violate Vultr's Acceptable Use Policy, such as media servers, robodialers, and shopping bots

Payments and Rates

These payment rates are guidelines; we evaluate each article individually. We base payments on the amount of original writing, excluding code blocks. We reduce our payment offer substantially for articles that do not comply with this guide. If our team discovers technical errors or needs to edit your article, you can expect to receive a much lower payment offer. We much prefer to pay you the full amount, so please carefully proofread and test your work before submitting it. We review your account for payment eligibility. For PayPal payouts, your PayPal account must allow you to receive payments. We do not process PayPal requests (to Vultr) or donation pages.

New Articles

New articles that are ready to publish without editing by Vultr are eligible for the highest payments and an author's byline.

  • New articles greater than 1500 words are eligible for up to $600.

  • New articles between 750 and 1500 words are eligible for up to $300.

  • New articles less than 750 words are eligible for up to $150.

Article Ports

We pay 50% of the new article rate, up to a maximum of $300, for ports of existing articles. Ports are guides rewritten for different platforms, such as an Ubuntu installation guide adapted to support FreeBSD. Ports should contain important new information and should not plagiarize the original article. Ports with only minor differences are not eligible.

Article Updates

We pay 50% of the new article rate for updates based on the amount of new content. Updates should contain significant new information and should not plagiarize the original article. Updates with only minor differences are not eligible.

Topics

Users reading your articles are primarily interested in server administration and applications. Therefore, our documentation library consists of these major categories:

  • Installation Guides are step-by-step installation and configuration instructions. The majority of our documents are installation guides.

  • Quickstart Guides are useful for users who need a cheat sheet. For example, they know they need to open a port in a firewall but don't know the exact command.

  • Best Practices are short documents that explain the best way to do a particular task.

  • Troubleshooting Guides are step-by-step instructions to resolve common problems.

  • Frequently Asked Questions are common questions with short answers, rarely more than one paragraph, and link to other documents as much as possible.

Our Values

Vultr values documentation that is comprehensive, accurate, and understandable.

Comprehensive

Our documentation is comprehensive. Each article has all the information required.

  • Cover each topic thoroughly, link to existing Vultr articles for prerequisites, and suggest other linked information that the reader should follow.

  • Your article should not make assumptions about the reader's knowledge. If background knowledge is required, describe it in the Prerequisites section along with relevant links to learn more when possible.

  • Your article must include all the steps required, from initial deployment to the final working condition, including all security requirements to harden the setup for production use.

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

  • Give the reader all the background information needed to understand and adapt the article to their needs. Teach them the concepts through your examples and explanation rather than only instructing them to copy and paste blocks of code and commands.

  • Each article should have a detailed explanation of the commands used, including any options and flags. Every code block should explain what it does and how it works so the reader can adapt it for their specific use case. When you tell the reader to do something, explain why you're asking the reader to make those changes. These details give readers the information they need to grow their skills.

  • When describing everyday tasks such as adding a sudo user, or updating the server, link to one of our reference or best practice articles.

  • Refrain from linking to articles outside Vultr unless there's no existing Vultr documentation and you cannot summarize the information in your article. In those cases, it may be appropriate to write a background Vultr article first and then link it to your main article.

Accurate

Our documentation is accurate. The articles are tested and proven to work.

  • Vultr requires authors to test their articles by following them exactly as written on fresh servers.

  • We provide authors with Vultr account credit to ensure they test their articles.

  • Our editing team also runs a quality test before publication to verify the authors are testing their work and following industry best practices.

Understandable

Our documentation is understandable.

  • 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

You'll find more information about writing in plain language at the end of this guide.

Style Requirements

This section describes the required style elements you should follow when writing your articles.

Write in Second Person

Documentation is not a blog post. When writing documentation, you should use second-person pronouns, not first-person. The second person directly addresses the reader as you.

Use second person pronouns: you, your, and yours.

Correct: Your server is deployed in New York.

Don't use first person singular pronouns: I, me, my, and mine.

Not correct: I will explain how to deploy a server in New York.

Be cautious with first-person plural pronouns: we, us, our, and ours. These should only refer to Vultr.

Correct: Choose our New York datacenter to deploy the server.

Not correct: We will learn how to deploy a server in New York.

If you must use the third person, avoid the gendered pronouns he, she, his, and hers. Instead, use they and their.

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

Exceptions to the Rule: Times when Passive Voice is Preferred

Although you should prefer active voice, there are some exceptions where passive voice is better, like when the system performs the action or it's unknown (or obvious) who or what is acting.

  • Active voice, but awkward: The developers scheduled the database to update weekly.

  • Passive voice, better phrasing: The database is updated weekly.

You can also use passive voice to avoid blaming the user directly for an error. For example:

  • Active voice, but not friendly: If the installation fails, you probably entered wrong information in the configuration file.

  • Passive voice, but friendlier: If the installation fails, wrong information probably was entered in the configuration file.

Use Task-focused Language

Use motivational language that focuses on the reader's outcome. Instead of explaining what the reader will learn, focus on what the reader will do.

Instead of saying, "Today, you'll learn how to install Kubernetes," focus on the result: "At the end of this article, you will have a working Kubernetes cluster."

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.

Use Present Tense

The reader usually performs the 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 the future tense.

Use an Implied Subject

It's common to omit you in instructional steps when 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 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.

Also, make sure to use the correct spelling.

Product Name 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 usually is lowercase, Vultr follows the Wikipedia Manual of Style for Trademarks. Here are some examples:

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

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

Avoid "Here" for Links

You should avoid here or click here for links when writing documentation. Instead, the link should describe itself to help the reader understand where it goes and improve search engine optimization (SEO). You should avoid links like these:

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



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

Instead, write those links as:

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



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

Descriptive links are friendlier for search engines and help the reader understand the link's context.

Slang, Jokes, Metaphors, and Hype

Please avoid advocacy and promotional hype in your documentation, as well as slang, jargon, jokes, idioms, metaphors, idioms, clichés, oxymorons, and euphemisms. Instead, focus on the facts, tasks, purpose, and actual user benefit.

  • Avoid this: FoobarDB version 12 is armed to the teeth with amazing high-availability features that will blow your mind.

  • Instead, say this: FoobarDB version 12 supports high availability with hot standby and failover.

Use English and US Spelling

  • Write your article in English.

  • 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

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.

Redundant Date Phrasing

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.

Midnight and noon

Don't use ambiguous constructions like 00:00 a.m. or 12:00 p.m. Instead, use midnight and noon.

  • Correct: The scheduler cleared the cache at noon.

Punctuation

  • Avoid exclamation points! They are not appropriate for technical documentation.

  • Use one space after a period between sentences.

  • Use the Oxford Comma to avoid confusion. Documentation must be unambiguous.

Acronyms

Define acronyms before their 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) cluster.

Steps in Narrative Form

Do not use first, next, finally, or lastly in a 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.

Instead, use an ordered list to describe the steps like this:

1. Read the program guidelines.

1. Read the style guide.

1. Write an article.

1. Submit the article to Vultr.

Note that Vultr always uses 1. as the list marker. This Markdown format allows you to move, add, and delete items without renumbering.

Also, don't use the adverb forms of steps like firstly, secondly, thirdly, or lastly.

Uncomparable Modifiers

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

  • extremely unavoidable

  • absolutely false

  • very final

  • increasingly impossible

Complex Phrases

Vultr prefers plain language over complex phrases. For example:

  • 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

Screenshots and Images

Use images sparingly in the documentation. Screenshots may often change, leaving your article out of date, and they are more complicated to edit than text descriptions. If you use images, ensure your text descriptions give enough information for assistive technology readers who cannot see the image. You must add alternative text that describes each image for accessibility. Do not depend on pictures to show 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.

Example Network Addresses

When writing networking examples, use these addresses:

Preferred Terminology

Vultr prefers to use these terms in our documentation.

Customer Portal

The customer portal is the web-based user interface at https://my.vultr.com.

Vultr Managed Databases

  • If referring to the product category, use Vultr Managed Databases.

  • If referring to a specific database engine such as MySQL, PostgreSQL, or Redis, use:

    • Vultr Managed Databases for MySQL

    • Vultr Managed Databases for PostgreSQL

    • Vultr Managed Databases for Redis

  • If not referring specifically to Vultr's implementation, use:

    • managed databases

    • managed MySQL

    • managed PostgreSQL

    • managed Redis

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

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.

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.

Since versus Because

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.

Current

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.

Let's

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.

Login versus Log in

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.

Setup versus Set up

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 versus After

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.

Oxymorons

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

So

Avoid using so at the beginning of a sentence.

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

Simple

Words like simple, straightforward, easy, simply, obviously, and just, are subjective and alienating. They aren't words describing the task; they presume the reader's skill level. Some authors use these words to encourage the reader, but they often frustrate a reader who runs into issues when the article claims the procedure is simple.

These words are lazy and unimaginative, and many other words could do the job better. Instead, give the reader clear explanations so they can be successful.

Avoid Congratulations!

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

Structure

Our articles are arranged into logical sections:

  • Title

  • Introduction

  • Prerequisites

  • Main content

  • Next Steps and Reference

Title

The article's title is the only H1-level heading (#) allowed, but you won't include it in your Markdown. Instead, when you submit an article for review, put the title in the Title field of the article submission form. Usually, titles should be less than 60 characters. A typical title should state the goal of the article and the key technology used. For example:

How to [Do a Task] with [Software Tools] on [Operating System]

We may edit your title for SEO or other purposes.

The Introduction

The introduction sets the reader's expectations, motivates them to read the rest of the article, and summarizes what they will do. It's usually three paragraphs or fewer. Think about these questions when writing your introduction.

  • What is the article about? Is it an installation guide, a reference guide, a quickstart, a description of an architectural pattern, or something else? What software will the reader use?

  • Why should the reader keep reading your article? What will they learn? What are the benefits to the reader?

  • What will the reader do? In the end, will they have set up a new server, built an application, secured their data, learned a new skill, or something else?

Organize your article by aligning your main content with the points made in the introduction. A strong introduction helps the reader quickly decide if they should keep reading.

Keep focusing on the article's solution instead of the reader or the technology. Don't use phrases like "you will learn how to," which place the focus on the reader. Instead, use phrases like "you will install," or "you will set up."

Likewise, if your article is about building an application in Go, keep the introduction's focus on the application and the solutions it provides instead of explaining the history of the Go programming language.

Prerequisites

The prerequisites section is where you explain what the reader should have or do before they follow the article. Your article should take a reader from the initial deployment of a vanilla image, through the first SSH to the server, to a completed solution.

You should include information like:

  • The type and number of servers to deploy, including the distribution, plan size, and network requirements

  • Common software stacks to deploy, like LAMP or Docker

  • DNS settings

  • Local workstation configuration or software requirements

  • Accounts required on other services like social media or other remote APIs

  • Links to conceptual articles or background articles that will assist the reader

This section should be formatted as a list of steps for the reader to follow. Each point should link to an existing article that explains the steps required to complete that point.

If no Vultr article exists for a prerequisite point, you can link to official product documentation or (preferably) request to write the prerequisite article. By using existing documentation for prerequisite steps, you can be assured the content is correct. If a prerequisite step changes, Vultr can update that one source of truth instead of updating many articles which have the prerequisite steps included inline.

Be specific. Telling the reader they "should be familiar with SQL" without a link for context isn't helpful. Instead, spell out the specifics and give a link for more information, like this: "You should be familiar with MySQL views and stored procedures. See this article to build your skills."

Main Content

The article's main content explains all the steps that a reader needs to follow and why they need to do it a particular way. Each major step should begin with an H2 (##) heading.

Terminal Commands

Each command a reader must run in the terminal should be in a separate code block.

  • Before each block, give a description that explains what the command does.

  • After the code block, explain more details about the command, such as what the arguments do and why your reader should use them.

  • If you need to show output, use a separate code block.

Here's an example in Markdown of how a command and its output should appear in Vultr's documentation.

Run the following command to display a list of IP addresses for `www.example.com`.



    $ dig +short www.example.com



The `+short` parameter instructs `dig` to display nothing except the short form of the answer.



Output:



    192.0.2.100

    192.0.2.101

    192.0.2.102

If your reader needs to be in a specific directory or change to a new one, be sure to include those commands.

When editing a file, always introduce it by describing its purpose, then explain what changes the reader will make. This will assist the reader when they need to customize, update, or troubleshoot issues later.

Explicitly tell the reader to create or open each file in an editor. We prefer nano for documentation if it's available; otherwise, use vi.

Transitions

Each major step should briefly introduce what the reader will do and have a closing describing what the reader did and what needs to happen next. The transitions give the reader context to help them follow the article. It's good writing form to vary your wording and avoid repeating the language from the step title.

Next Steps and Reference

Rather than a Conclusion section that merely restates what the reader has accomplished by following your article, you should use this opportunity to suggest the next steps and give links to reference material. This is also a good place to link other related Vultr documentation.

Vultr-Flavored Markdown

Use Vultr-flavored Markdown when writing for Vultr Docs. Vultr-flavored Markdown is Vultr's in-house, non-standard Markdown format. Please pay special attention to code blocks and keystroke symbols. The main differences between Vultr-flavored Markdown and other common Markdown flavors are:

  • Vultr Markdown does not allow inline HTML. You may only use plain text with Markdown formatting.

  • Vultr uses a special syntax to represent keystrokes, which is explained later in this article.

  • Fenced code blocks are not supported.

  • Code blocks do not support highlighting or line numbers.

  • Vultr Markdown does not support tables of any kind.

For the best results, please follow the tips that follow. To check your formatting, please use the Preview tab in the article submission form.

Paragraphs and Line Breaks

Example:

A paragraph is simply one or more consecutive lines of text separated by blank lines. Normal paragraphs should not be indented with spaces or tabs.



Add a blank line to start a new paragraph.

Result:

A paragraph is simply one or more consecutive lines of text separated by blank lines. Normal paragraphs should not be indented with spaces or tabs.

Add a blank line to start a new paragraph.

Headers

Vultr automatically adds the article title as an H1 heading when publishing. Do not include H1 (#) in your article.

## This is an H2

### This is an H3

#### This is an H4

##### This is an H5

###### This is an H6

Blockquotes

Example:

> This is a **blockquote** with two paragraphs. Lorem ipsum dolor sit amet,

> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

>

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse

> id sem consectetuer libero luctus adipiscing.

Result:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,

consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse

id sem consectetuer libero luctus adipiscing.

Nested blockquote

Example:

> This is the first level of quoting.

> 

>> This is nested blockquote.

> 

> Return to the first level blockquote.

Result:

This is the first level of quoting.

This is nested blockquote.

Return to the first level blockquote.

Ordered lists

If the reader must perform steps in a particular sequence, use an ordered list. Vultr always uses 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 guide.

1. Read the style guide.

1. Request an assignment.

1. Write the article.

Result:

  1. Read the program guide.

  2. Read the style guide.

  3. Request an assignment.

  4. Write the article.

Ordered lists with 2 paragraphs

Example:

1. This is a list item with two paragraphs. Indent the second paragraph 4 spaces to align with the list.



    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.



1. This is the second list item.

Result:

  1. This is a list item with two paragraphs. Indent the second paragraph 4 spaces to align with the list.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

  2. This is the second list item.

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

Result:

Please gather the following items:

  • Bread

  • Apples

  • Very small rocks

  • Lead

  • A duck

Code Blocks

Code blocks are indented with 4 spaces at the beginning of each line.

  • Use four spaces to create a code block.

  • Do not use triple backticks for fenced code blocks.

  • Do not use single backticks.

  • Do not use tabs.

Example:

<- Beginning of line



    int main() {

        std::cout << "Hello World!";

        return 0;

    }
  • Code blocks inside ordered or unordered lists are indented by eight spaces at the beginning of each line.

  • Text indented by four spaces becomes part of the list item.

Example:

1. This is item one.



    Here is the code for item one.



        int main() {

            std::cout << "Hello World!";

            return 0;

        }



2. This is item two.

3. This is item three.

Result:

  1. This is item one.

    Here is the code for item one:

    int main() {
    
        std::cout << "Hello World!";
    
        return 0;
    
    }
    
  2. This is item two.

  3. This is item three.

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.

Example:

Use the `printf()` function.

Result:

Use the printf() function.

Literal backticks

Wrap a command with two backticks if you need to show a literal backtick.

Example:

There is a "literal backtick (`) "here.

Result:

There is a "literal backtick (`) "here.

Inline Links

We support inline links.

Example:

This [example inline link](http://example.com/ "The Link Title") is titled "The Link Title".

[This link](http://example.net/) has no title attribute.

Result:

This example inline link is titled "The Link Title".

This link has no title attribute.

Do Not Use Reference Links

Please do not use reference-style links like this example:

Some popular search engines are [Google][1], [Yahoo][2], and [MSN][3].



[1]: http://google.com/ "Google"

[2]: http://search.yahoo.com/ "Yahoo Search"

[3]: http://search.msn.com/ "MSN Search"

Automatic links

Wrap URLs with angle brackets to make an automatic link.

Example:

Make automatic links: <http://example.com/> and <address@example.com>

Result:

Make automatic links: http://example.com/ and address@example.com

Emphasis

  • Use single underscores to make italic text.

    Use single underscores to make italic text.

  • Use double asterisks to make bold text.

    Use double asterisks to make bold text.

Underscores

It's common to have variable names in technical documents with underscores. Be careful to escape your underscores to prevent unexpected italics.

Correct:

THE\_EXAMPLE\_VARIABLE

THE_EXAMPLE_VARIABLE

Incorrect:

THE_EXAMPLE_VARIABLE

THEEXAMPLEVARIABLE

Special Characters

Use a backslash to escape special characters.

Example:

\*this text is surrounded by literal asterisks\*

\\

\`

\*

\_

\{\}

\[\]

\(\)

\#

\+

\-

\.

\!

Result:

*this text is surrounded by literal asterisks*

\

`

*

_

{}

[]

()

#

+

-

.

!

Keystrokes

Represent literal keystrokes with Vultr's shortcodes. Distinguish uppercase/lowercase with the shift key.

:key_x: is a lowercase "x".

:key_shift:+:key_x: is an uppercase "X".

X is a lowercase "x".

SHIFT+X is an uppercase "X".

Example Usage

Save the file by pressing :key_ctrl:+:key_x:, then :key_y:.

Result:

Save the file by pressing CTRL+X, then Y.

Alphabet

:key_a: :key_b: :key_c: :key_d: :key_e: :key_f: :key_g:

:key_h: :key_i: :key_j: :key_k: :key_l: :key_m: :key_n:

:key_o: :key_p: :key_q: :key_r: :key_s: :key_t: :key_u:

:key_v: :key_w: :key_x: :key_y: :key_z:

Result:

A B C D E F G

H I J K L M N

O P Q R S T U

V W X Y Z

Numbers

:key_1: :key_2: :key_3: :key_4: :key_5:

:key_6: :key_7: :key_8: :key_9: :key_0:

Result:

1 2 3 4 5

6 7 8 9 0

Function Keys

:key_f1: :key_f2: :key_f3: :key_f4: :key_f5: :key_f6:

:key_f7: :key_f8: :key_f9: :key_f10: :key_f11: :key_f12:

Result:

F1 F2 F3 F4 F5 F6

F7 F8 F9 F10 F11 F12

Symbols

:key_tilde: :key_grave: :key_exclamation: :key_at: :key_pound:

:key_dollar: :key_percent: :key_carat: :key_ampersand: :key_asterisk:

:key_lparen: :key_rparen: :key_dash: :key_underscore: :key_plus:

:key_equals: :key_lbracket: :key_lbrace: :key_rbracket: :key_rbrace:

:key_pipe: :key_backslash: :key_semicolon: :key_colon: :key_quote:

:key_apostrophe: :key_lt: :key_comma: :key_gt: :key_period:

:key_question: :key_forwardslash: :key_space: :key_spacebar:

Result:

~ ` ! @ #

$ % ^ & *

( ) - _ +

= [ { ] }

| \ ; : "

' < , > .

? / SPACE SPACE

Special Keys

:key_esc: :key_backspace: :key_tab: :key_caps: :key_capslock:

:key_enter: :key_return: :key_shift: :key_control: :key_ctrl:

:key_super: :key_win: :key_command: :key_alt: :key_meta:

:key_printscreen: :key_sysrq: :key_scrolllock: :key_pause: :key_break:

:key_delete: :key_end: :key_pagedown: :key_pgdn: :key_insert:

:key_home: :key_pageup: :key_pgup: :key_up: :key_left: :key_down:

:key_right: :key_numlock:

Result:

ESC BACKSPACE TAB CAPS CAPS

ENTER RETURN SHIFT CTRL CTRL

SUPER WIN COMMAND ALT META

PRINTSCREEN SYSRQ SCROLLLOCK PAUSE BREAK

DELETE END PGDN PGDN INSERT

HOME PGUP PGUP UP LEFT DOWN

RIGHT NUMLOCK

Tables

Do not use tables. Vultr-flavored Markdown does not support tables of any kind.

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

Edit Your Article

Great technical writing requires great writing, not just solid technical knowledge. Your article might have all the needed technical information, but if it's poorly organized and sloppily written, it's not useful to the reader.

  • Always carefully proofread and edit your article before submitting it to Vultr for review.

  • Follow the standard rules of English grammar and punctuation.

  • Use the standard format described in this style guide.

Many authors use tools like these to review their articles before submitting them to Vultr Docs:

These are helpful, but none of them are a substitute for a human editor. We recommend using resources like:

Plain Language Resources

If you'd like to learn more about plain language, see these resources:

Plain Language Examples

Here are three examples of the same information, written in different styles.

  • Example 1 is too wordy.

  • Example 2 is too brief.

  • Example 3 is in plain language, which we prefer.

Please compare these to see the differences:

Example 1: Content is too Wordy

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

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.

Example 2: Content is too Brief

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

Connect to the server and run:

>

   $ sudo snap install --classic certbot

Example 3: Content is Plan Language (preferred)

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

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

>

       $ ssh myuser@exampleserver

>

  1. Install Certbot with Snap. Certbot requires you to use the --classic flag to install with Snap.

>

       $ sudo snap install --classic certbot

You should strive to use plain language in all your documentation.

Frequently Asked Questions

How do I include images in my articles?

Our article submission system does not allow directly embedding images in Markdown for security. If your article includes images, please upload it to a public location such as imgur.com, and then use a standard Markdown image directive like this:

![Alt text for image](https://i.imgur.com/example-filename.png)

Important note about images: Articles in Vultr's documentation library must be accessible, which means all images need alternative descriptive text. As a general rule, use images sparingly unless required. If you use images, include sufficient information so a person who cannot see the image can use your article.

Can I write articles anonymously?

You can choose to be anonymous instead of publishing your name on your articles.

I'd like author credit, but I prefer to use an alias instead of my real name.

Vultr does not publish aliases for author credit. You can leave the author's name blank if you prefer not to use your real name.

Why do I have to link a payment method to my account? Do I have to pay to write for Vultr Docs?

You do not have to pay to write for Vultr Docs, but we need a linked payment method to verify your account and prevent fraud. When you link your credit card, you can choose "I just want to link my credit card - $0.00 deposit", and you will not be charged.

Do you have a list of available assignments?

Yes, please see our available assignment list.

I wrote an article but didn't request an assignment. What do I do?

Before you submit your article, please request an assignment. If you want to write about a topic that isn't on our available assignment list, please let us know. If it's appropriate for Vultr Docs and doesn't duplicate another article, we'll add it to the list and assign it to you. We require this step to prevent assignment conflicts.

How can I make as much money as possible?

Some authors rush to deliver multiple articles to maximize their income. Unfortunately, these articles are usually low quality and require our team to edit them, resulting in lower payments if published. However, you can increase your payments by following a few tips:

  • Thoroughly understand your topic and write unique content instead of hastily rewording another guide you found online.

  • Don't submit your first draft. We have editing tips in our style guide.

  • Test your article by performing all the steps exactly as you wrote them.

The secret to earning money by writing for Vultr Docs is straightforward: Deliver tested, edited, valuable content.

Why didn't you agree to publish my article?

Requesting an article assignment or accepting an assignment does not create any obligation by Vultr to publish your article. We may ask you to make changes or corrections, or the team may decline to publish your article without an explanation. We will make a payment offer after reviewing your article.

Can you send me a copy of my article?

Unfortunately, no. Please save a copy of your article before submitting it to us.

Will you tell me why my article was not published?

We do not provide reviewer notes if we choose not to publish your article.

My article meets all the guidelines, but it wasn't published. Why?

Not every article will be accepted for publication, even if it meets all program guidelines. The decision to publish an article depends on many business factors, and Vultr may decline to publish articles at our sole discretion without a detailed explanation.

I sent an outline, and it was approved, but you didn't publish my article. Why?

Our approval of an outline concept does not create a contractual obligation to publish an article. It only means the outline isn't on our list of unpermitted topics.

Can I advertise myself as a Vultr employee on my LinkedIn profile or blog?

Payment for articles does not constitute an employer-employee relationship. Therefore, authors may not represent themselves as Vultr employees online.

I was offered less than expected. Why?

These payment rates are guidelines; we evaluate each article individually, prepare a payment proposal, and obtain your consent before publishing. We will not publish your article unless you agree with our proposed payment.

Can you pay in Bitcoin or Payoneer?

We do not pay in Bitcoin or Payoneer. You may choose to receive payments through PayPal or Vultr account credit.

Must my PayPal email address match my Vultr account email address?

They do not need to match. You are welcome to use a different PayPal address than your Vultr email address.

Can I write articles about virtualization technologies such as VirtualBox, VMWare, KVM, or XEN?

Yes, if the article is specific to Vultr Bare Metal. Vultr cloud servers do not support nested virtualization.

Can I host my code samples on GitHub, GitLab, or elsewhere?

No, you must include all code samples in your article. However, at our discretion, we may choose to migrate your code samples to the Vultr Docs GitHub repository.

How long does it take to receive payment after I submit an article?

After you submit your article, our team will review it. The review time varies; we publish a current estimate on the assignment dashboard. If your article is approved and you accept our payment proposal, the payment team typically makes the payment within five business days.

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. If you have a question about the Vultr Docs Creator program, please contact us. We appreciate your feedback.

Want to contribute?

You could earn up to $600 by adding new articles.