}})
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 and Terminology, a Markdown and terminology reference
To get published quickly, we recommend that you read the Style and Structure sections in their entirety before you begin working on your article.
You can use the Formatting section of this guide along with our Markdown previewer as references while writing your article.
We also have a technical best practices guide which outlines our tech-focused recommendations.
We have developed article templates in Markdown format you can use as a starting point for your article. We strongly recommend using one of these templates to plan and develop your article.
Read on to learn about our article style.
Style
DigitalOcean articles don’t use a particular style manual like the Chicago Manual of Style. Instead, we strive to ensure all DigitalOcean tutorials are:
- Comprehensive and written for all experience levels
- Technically detailed and correct
- Practical, useful, and self-contained
- Friendly but formal
These principles guide authors to create articles, tutorials, and other learning materials that help people solve their problems and grow as developers.
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 the concepts, not just copy and paste code and commands.
We avoid words like “simple,” "straightforward,” "easy,” “simply,” “obviously,” and “just,” as these words do make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.
}})
Technically detailed and correct
Our articles are technically accurate and follow industry best-practices. They also provide more details than just the code and commands. We don’t provide large blocks of configuration or program code and ask readers to paste it into their text editor, trusting us that it works. We provide all the details necessary for the readers to understand it.
Every command should have a detailed explanation, including options and flags as necessary. Every block of code should describe what it does and why it works that way. When you ask the reader to execute a command or modify a configuration file, first explain what it does and why you’re asking the reader to make those changes. These details give readers the background they need to grow their skills.
Authors test their tutorials to ensure they work by following them exactly as written on fresh servers. This ensures accuracy and identifies missing steps. Our editors also test these articles as part of the review process to ensure a great learning experience for the reader.
Practical, useful, and self-contained
Once a reader has finished a DigitalOcean article, they should have installed, built, or set up something from start to finish. We emphasize a practical approach: at the end of an article, the reader should have a usable environment or an example to build upon.
What this means for the writer is that their article should cover the topic thoroughly. Authors should link to existing DigitalOcean articles, if available, to set up prerequisites that readers should follow before beginning the tutorial, and link to available DigitalOcean articles to provide additional information in the body of the tutorial. Authors should only send readers offsite to gather information if there’s no existing DigitalOcean article and the information can’t be added to the article directly in a short summary.
Friendly but formal
Our tutorials aim for a friendly but formal tone. This means that articles do not include jargon, memes, excessive slang, emoji, or jokes. As we’re writing for a global audience, we aim for a tone that works across language and cultural boundaries.
Unlike blog posts, we do not use the first person singular (e.g. “I think …”). Instead, we encourage the use the second person (e.g. “You will configure …”) to keep the focus on the reader and what they’ll accomplish. In some cases, we’ll use the first person plural (e.g. “We will install …”“).
We encourage motivational language focused on outcomes. For example, instead of "You will learn how to install Apache”, try “In this tutorial you will install Apache”. This motivates the reader and focuses on the goal they need to accomplish.
Finally, the language of our tutorials honors diverse human experiences and follow our Community Code of Conduct. That means we avoid offensive language or other content that is in reference to (but not limited to) age, disability, ethnicity, gender identity or expression, level of experience, nationality, neurodiversity, personal appearance, race, religion, political affiliation, sexual orientation, socioeconomic status, or technology choices.
Structure
DigitalOcean articles have a consistent structure, which includes an introduction, a conclusion, and any prerequisites necessary for a reader to get started. However, the specific structure depends on the type of article.
Procedural tutorials walk the reader through accomplishing a complex task. The structure for one of these articles looks like this:
- Title (Level 1 heading)
- Introduction (Level 3 heading)
- Goals (Optional)
- Prerequisites (Level 2 heading)
- Step 1 — Doing the First Thing (Level 2 heading)
- Step 2 — Doing the Next Thing (Level 2 heading)
- …
- Step n — Doing the Last Thing (Level 2 heading)
- Conclusion (Level 2 heading)
Conceptual articles will have a title, an introduction, and a conclusion, but might not always have a prerequisites section, a Goals section, and might not follow the “Step” convention:
- Title (Level 1 heading)
- Introduction (Level 3 heading)
- Prerequisites (optional) (Level 2 heading)
- Doing the First Thing (Level 2 heading)
- Doing the Next Thing (Level 2 heading)
- …
- Doing the Last Thing (Level 2 heading)
- Conclusion (Level 2 heading)
Some articles are more focused on a very small specific task or solution, and they’ll often have a title, a small introductory sentence, and a conclusion at the end. Those articles will have a structure like this:
- Title (Level 1 heading)
- Introduction paragraph
- Prerequisites (optional) (Level 2 heading)
- Article body
- Conclusion paragraph
Our article templates have this structure already written for you in Markdown, and we encourage you to use these templates as a starting point for your own articles.
Title
When you write your title, think carefully about what the reader will accomplish by following your tutorial. Try to include the goal of the tutorial in the title, not just the tool(s) the reader will use to accomplish that goal.
A typical title for a procedural tutorial follows this format: How To <Accomplish a Task> with <Software> on <Distro>.
For example, if your tutorial is about installing the Caddy web server, the goal is likely to host a website. If your tutorial is about installing FreeIPA, the goal might be to set up centralized Linux authentication.
Titles that include the goal (like “How To Create a Status Page with Cachet on Debian 8”) are generally more informative for the reader than titles that don’t (like “How To Install and Set Up Cachet on Debian 8”).
Introduction
The first section of every article is the Introduction, which is usually one to three paragraphs long. The purpose of the introduction is to motivate the reader, set expectations, and summarize what the reader will do in the article. Your introduction should answer the following questions:
- What is the tutorial about? What software is involved, and what does each component do (briefly)?
- Why should the reader learn this topic? What are the benefits of using this particular software in this configuration? What are some practical reasons why the reader should follow this tutorial?
- What will the reader do or create in this tutorial? Are they setting up a server and then testing it? Are they building an app and deploying it? Be specific, as this provides the motivation readers need and gets them excited about the topic.
- What will the reader have accomplished when they’re done? What new skills will they have? What will they be able to do that they couldn’t do before?
Answering these questions in your introduction will also help you design a clear and reader-focused tutorial, as you’ll align the steps
Keep the focus on the reader and what they will accomplish. Instead of using phrases like “we will learn how to”, use phrases like “you will configure” or “you will build”. This goes a long way to motivate the reader and get them excited about your topic. In addition, keep the focus on the problem the reader is solving rather than the technology. For example, if a tutorial is about building a project with React, you can focus your introduction on the project rather than explaining what React is and its history.
Goals
Some larger procedural tutorials use the optional Goals section to separate the tutorial’s context, background explanation, and motivation from the details of the final configuration. You should only use this section if your tutorial requires multiple servers, has a large software stack, or otherwise has a particularly complicated purpose, method, or result.
Some good examples include this Prometheus tutorial’s introduction and this Pydio tutorial’s goals.
Most tutorials will not have a Goals section.
Prerequisites
The Prerequisites sections of DigitalOcean articles have a very specific format and purpose.
The purpose is to spell out exactly what the reader should have or do before they follow the current tutorial. The format is a bulleted list that the reader can use as a checklist. Each bullet point must link to an existing DigitalOcean tutorial that covers the necessary content if one exists. This allows you to rely on existing content known to work instead of starting from scratch.
Our systems and DevOps tutorials take the reader from a fresh deployment of a vanilla distribution image to a working setup, so they should start with the first SSH connection to the server or include a prerequisite tutorial that does.
Common prerequisite for system administration and DevOps tutorials include:
- The number of servers necessary, including distribution, initial server setup, and any additional necessary options (like memory requirements, DO API keys, IPv6, or private networking).
- Software installation and configuration, such as Apache, a LAMP stack, or databases.
- Required DNS settings or SSL certificates.
Our software development tutorials work in a similar fashion, providing the reader with all of the prerequisites they’ll need up front, including a prerequisite for the development environment.
