DigitalOcean's Writing Guidelines
DigitalOcean is excited to continue building out its collection of technical articles related to server administration and software engineering. To ensure that DigitalOcean articles have consistent quality and style, we have developed the following guidelines.
There are three sections in this guide:
- Style, our high-level approach to writing technical tutorials
- Structure, an explanation of our layout and content
- Formatting, a Markdown and terminology reference
To get published quickly, DigitalOcean community authors should read the style and structure sections in their entirety. Our templates are useful as a starting point for an article, and the formatting section of this guide along with our Markdown previewer can be used as references while writing.
DigitalOcean articles should be:
- Comprehensive and written for all experience levels
Our articles are written to be as clear and detailed as possible without making assumptions about the reader's background knowledge.
We explicitly include every command a reader needs to go from their first SSH connection on a brand new server to the final, working setup. We also provide readers with all of the explanations and background information they need to understand the tutorial. The goal is for our readers to learn, not just copy and paste.
- Technically detailed and correct
All of our tutorials are tested on new servers to ensure they work from scratch. Every command should have a detailed explanation, including options and flags as necessary. When you ask the reader to execute a command or modify a configuration file, first explain what it does or why they're making those changes.
- Practical, useful, and self-contained
Once a reader has finished a DigitalOcean article, they should have installed or set up something from start to finish. We emphasize a practical approach: at the end of an article, we should leave the reader with a usable environment or an example to build upon.
What this means for the writer is that their article should cover their topic thoroughly and, where necessary, should link to another DigitalOcean article to set up prerequisites. Authors shouldn't send readers offsite to gather information that could easily be added to the article.
- Friendly but formal
Our tutorials aim for a friendly but formal tone. This means that articles do not include jargon, memes, or excessive jokes. This also means that, unlike blog posts, we do not use the first person singular (e.g. "I think ..."). Instead, we use the first person plural (e.g. "We will install ...) or second person (e.g. "You will configure ...").
Our tutorials have a consistent structure composed of the following sections:
- Goals (Optional)
- Step 1 — Doing Something
- Step 2 — Doing Something Else
- Step n — Doing the Last Thing
Our article templates have this layout in Markdown. You can use these templates as a starting point for writing your own article.
Title, Introduction, and Goals
A typical title follows the format of How To <Do a Task> with <Software> on <Distro>.
The first section of every tutorial is the Introduction, which is usually 1 to 3 paragraphs long. The introduction should answer the following questions:
- What is the goal of the tutorial? What will the reader accomplish if they follow it?
- What software is involved, and what does each component do (briefly)?
- What are the benefits of using this particular software in this configuration? What are some practical reasons why the reader should follow this tutorial?
If your tutorial has a particularly complicated purpose, method, or result, you can add an optional Goals section after the introduction to elaborate further. This section can be useful for multi-server setups and large software stacks.
The prerequisites section should contain a bulleted list with all of the required items, pieces of software, and configurations the reader will need before following the tutorial.
Remember that your tutorial should get the reader from the deployment of a vanilla distribution image to a working setup. If your tutorial is not going to start with the first SSH connection to the server, you need to link to another DO tutorial that does.
Common prerequisite bullet points include:
- The number of servers necessary, including which distribution and what size.
- A link to a tutorial about setting up a sudo non-root user for the appropriate distribution, like this one for Ubuntu 16.04.
- A link to a tutorial about installing prerequisite software, such as Nginx. This can be a part of a tutorial, e.g. "Follow Steps 1 and 2 from ...".
- Required DNS settings or SSL certificates.
The reader should be able to use the prerequisites as a checklist. When you test your tutorial, make sure you follow all of the prerequisite tutorials exactly, so that everyone uses the same starting point. If you changed a variable or completed an optional step from one of the prerequisites, make sure to note that.
The steps are the parts of your tutorial where you describe what the reader needs to do.
Each step should begin with a sentence that describe the context or purpose of the step. Try to avoid repeating the title of your step in this introductory sentence. Make sure not to start a section with a contextless instruction or command.
All commands in a step should be on their own line in their own code block, and each command should be preceded by a description. Similarly, always introduce a file or script by describing its general purpose, then explain any changes that the reader will be making in the file. We do not want to encourage readers to copy and paste commands, files, or scripts without understanding them because they won't be able to customize, update, or troubleshoot their server in the long run.
Images provide a great way to quickly illustrate a point or provide additional clarification in a step. Use images for screenshots of GUIs, interactive dialogue, and diagrams of server setups. Don't use images for screenshots of code, configuration files, output, or anything that can be copied and pasted into the article.
At the end of a step, provide a short sentence to transition the reader to the next topic. Like the introduction, take care not to repeat the title of the next step in this sentence, but do tell the reader what they accomplished and where they are going next. If you end a step with a command or terminal output, the step often feels unfinished.
Write a brief conclusion for your tutorial to summarize what has been accomplished, and what the reader might want to do next.
DigitalOcean tutorials are formatted in the Markdown markup language. Daring Fireball publishes a comprehensive Markdown guide if you're unfamiliar with it. DigitalOcean also uses some custom Markdown. Examples of our custom Markdown are in the appropriate sections below.
Each section of our tutorials has a corresponding header: the title should be an H1 header; the introduction should be an H3 header; the goals, prerequisites, steps, and conclusion should have H2 headers. You can see this format in our Markdown article templates.
For procedural tutorials, step headers should include step numbers (numerical) followed by an em dash (—). Step headers should also use the gerund, which are -ing words. An example step header is Step 1 — Installing Nginx.
Use H3 headers sparingly, and avoid H4 headers. If you need to use subheaders, make sure there are two or more headers of that level within that section of the tutorial. Alternatively, consider making multiple steps instead.
Bold and Italics
Here's a list of items that should be bold:
- Visible text from a GUI
- Hostnames and usernames, like wordpress-1 or sammy
- Term lists
- Changing context for a command, such as switching to a new server or user
Italics should only be used when introducing technical terms. For example, the Nginx server will be our load balancer.
Code blocks should be used for:
- Commands the reader needs to execute to complete the tutorial
- Files and scripts
- Terminal output
- Interactive dialogues that are in text
Excerpts and omissions in files can be indicated with ellipses (. . .). If most of a file can be left with the default settings, it's usually better to show just the section that needs to be changed.
Do not include the command prompt in the code block. Instead, use DigitalOcean's custom Markdown as shown:
This is a non-root user command example: ```command sudo apt-get update ``` This is a root command example: ```super_user adduser sammy ``` This is a custom prefix command example: ```custom_prefix(mysql>) FLUSH PRIVILEGES; ```
This is how the above examples look when rendered:
This is a non-root user command example:
- sudo apt-get update
This is a root command example:
- adduser sammy
This is a custom prefix command example:
- FLUSH PRIVILEGES;
DigitalOcean's Markdown also includes labels and secondary labels. Use labels to mark code blocks containing the contents of a file with a filename. Use secondary labels to mark terminal output.
Denote a label by using
[label This is the label text] as the first line of the code block. Denote secondary labels by using
[secondary_label This is the secondary label text] as the first line of the code block. Labels look like this when rendered:
This is the label text
Label example: This is one line of the file This is another line of the file . . . This is a line further down the file
Secondary label example:
This is the secondary label textThis is some output from a command
In-line code formatting should be used for:
- Command names, like
- Package names, like
- Optional commands
- File names and paths, like
- Example URLs, like
- Ports, like
- Key presses, which should be in ALL CAPS and use a plus symbol, +, if keys need to be pressed simultaneously, like
Notes and Warnings
The DigitalOcean Markdown parser allows for custom note and warning code blocks to be used to display very important text.
Here's a Markdown example of a note and a warning (this is an image):
Here's the rendered result:
Note: This is a note.
Warning: This is a warning.
Any item that needs to be changed by the reader should be highlighted, like example URLs, lines in configuration files, etc. DigitalOcean's Markdown parser will use the <^> symbol to turn text red, even in an otherwise unformatted block or line.
This only works in line, meaning you need to highlight multiple lines individually; you cannot highlight multiple lines with one pair of symbols. If you reference a variable in a context where you would normally also use
in-line code formatting, you should use
Users, Hostnames, and Domains
Our default example username is sammy. You can also choose something descriptive where helpful, like webdav-kai or nsd.
your_server is the default hostname, though you are encouraged to choose something descriptive, especially in multi-server setups, like django_replica_1.
example.com is the default domain. For multi-server setups, you can choose something like
IP Addresses and URLs
your_server_ip, with in-line code formatting and variable highlighting, is the default way to show an IP address. You can show multiple IP addresses with names like
replica_private_ip. If you need to illustrate more realistic IP addresses, you can use
Example URLs that contain a variable the reader needs to customize should use code formatting with the variable highlighted. We default to using
http://your_server_ip/. However, live links should instead use the standard Markdown link style with no extra formatting.
Use the official website's capitalization of the name of their software. If the product website is not consistent with their capitalization, just be consistent within a single article.
Similarly, use the project's terminology for multi-server setups. Please be clear that the terms are coming from the project. For example, the Django project refers to the original server as the primary and the secondary server as the replica. The MySQL project refers to the original server as the master and the secondary server as the slave.
Images and Other Assets
If you're including images in your tutorial, please follow these guidelines:
- Include descriptive alt text so readers using a screen reader can rely on the alt text rather than the image.
- Use the
- Host images on imgur
- Make the image with as short a height as possible
If you make a mockup of a diagram for your tutorial, we will create a diagram in the DigitalOcean style. We'll also upload all images to DigitalOcean servers at publication time.
Here's a Markdown example for including images in your tutorial:
![Alt text for screen readers](http://imgur.com/your_image_url)
Occasionally you will want the reader to have access to a configuration file that is too long to display in the main body of the tutorial. DigitalOcean will host this file on our asset server. You can use standard link formatting to link to the file.
Follow this link to become a DigitalOcean author.