Advent of Technical Writing: Reviewing Digital Ocean's Documentation

This is a ✨ bonus ✨ post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

Digital Ocean documents common systems administration tasks, from creating SSH keys to installing popular software. They also publish other content, such as HTML and JavaScript turoaisl.

Digital Ocean's systems tutorials walk through everything from configuring SSH keys to setting up a web server using a tool like Apache 2 or NGINX. I found some of their tutorials immeasurably helpful to me when I was starting to learn about technology. Back when I reviewed some of their guides, I knew little about the web stack. I was exploring with curiosity in my spare time. Digital Ocean's documentation helped me learn about the web stack and, in the process, build more confidence in the command line and with Linux.

I want to dive deeper into the how behind the experience that I had with Digital Ocean's experience. What features and attributes does their documentation have that make it so notable? In this article, I will explore that question with reference to examples from a guide entitled "How To Install Nginx on Ubuntu 20.04". I recommend you keep the article open to the side while you are reading this blog post, if possible, as I will refer to features without direct quotes in the interests of brevity. Without further ado, let's get started!

Setting the reader on the right path: A version selector

When you work with operating systems, the area to which many of Digital Ocean's tutorials relate, versions matter. Instructions may vary between versions. Digital Ocean is not only conscious of this, but added a feature to their documentation with the importance of reading documentation for the right version in mind: you can select from a dropdown to find tutorials for different operating systems.

Here is what that feature looks like:

I can click a dropdown to select a new version. When I do, I am redirected to the appropriate article. This is an excellent idea. I learn both what other versions Digital Ocean has documented and I can efficiently navigate to the one I need if I have landed on a page with the wrong version. If the version of operating system I am using is not on the list, I know that Digital Ocean has not published a guide on the topic.

The introduction

Digital Ocean's content starts with concise introductions. In two paragraphs, the author introduced:

• What NGINX is;
• Why NGINX is useful, and;
• What we will accomplish in the guide.

From reading those two paragraphs, I can evaluate whether an article is likely to solve my problem.

After the introduction, the guide notes prerequisites in a section titled "Prerequisites". I like how this section is clearly distinguished from the introduction by using a heading. The prerequisites are direct, which removes room for ambiguity, and reference helpful resources where appropriate. Here is an excerpt from the preqresuiteis in the Nginx guide we are reviewing in this post:

Before you begin this guide, you should have a regular, non-root user with sudo privileges configured on your server. You can learn how to configure a regular user account by following our Initial server setup guide for Ubuntu 20.04.

The language is unambiguous, clear, and makes reference to a guide where I can learn more about how to meet the prerequisites.

Then, the tutorial begins.

Explaining the "whys"

This particular tutorial effectively explains the "whys" behind each command. This is particularly important for systems documentation since administrators need to know exactly what a command does before running it. Such knowledge can help them evaluate if they should run a command in the first place. Here is an example the "why" behind a command being clearly explained:

Since this is our first interaction with the apt packaging system in this session, we will update our local package index so that we have access to the most recent package listings. Afterwards, we can install nginx:

The explanation is concise.

Copyable code snippets

You can copy-paste all of Digital Ocean's code snippets using a "Copy" button that is clearly visible in every snippet. This makes working with the documentation more efficient. You don't need to manually copy each snippet.

Snippets with outputs do not have "Copy" buttons. This small detail reduces the chances someone copies an output into their terminal, which could cause problems because multi-line outputs could break into different lines. A beginner to the terminal may struggle to figure out how to get out of a situation where they pasted multiple lines of text in a terminal. Hiding the "Copy" button from output helps to prevent this situation entirely, and reduces the chance that any developer will copy text from the guide into their terminal they don't want.

Highlighted variables to substitute

When you are writing code snippets in documentation, there are some times when you need to include placeholder values. For example, a reader may need to substitute a variable with a file name, a directory path, or another value. Digital Ocean has a feature in their code snippets that visually highlights values that need substituted.

Here is an example:

Text that needs substituted has a different background color. This makes values that need to be changed stand out. With that said, the text highlighting is not the only cue. A reader can depend on the "your_example", etc. text, which is important as partially sighted readers or readers with a color blindness may not notice the background color changes.

Multi-step code examples are well written

Some commands in the article have two or three steps. For example, the article describes how to enable a firewall using ufw, the command to verify the firewall status, and the output from the verification. The author uses short transition sentences that effectively describe what each command does. The author also specifies what the output means, where relevant.

Here is the ufw example, except with the output removed for brevity:

You can enable this by typing:

bash sudo ufw allow 'Nginx HTTP'

You can verify the change by typing:

bash sudo ufw status

The output will indicated [sic] which HTTP traffic is allowed:

[output]

The author described two commands and an output in three sentences. The sentences are well connected and relevant to the subject of the section, which is "Adjusting the Firewall" according to the section title that corresponds with the code snippets.

Helping readers build a solid foundation of knowledge

Going a bit further than required to help a reader build foundational knowledge, or reach an "aha moment" where they feel confident with the content in a guide is a good idea.

The Digital Ocean Nginx guide includes a section called "Getting Familiar with Important Nginx Files and Directories" before the conclusion. This section outlines some key information that you can use when working with Nginx. While the information is not technically required to install Nginx (the stated goal of the guide), it does provide the reader additional context that they can use to build confidence with Nginx.

Referring to next steps

In the Digital Ocean Nginx guide conclusion, the author summarizes the article in a sentence, then links to other articles that would be effective reading:

Now that you have your web server installed, you have many options for the type of content to serve and the technologies you want to use to create a richer experience.

If you’d like to build out a more complete application stack, check out the article How To Install Linux, Nginx, MySQL, PHP (LEMP stack) on Ubuntu 20.04.

In order to set up HTTPS for your domain name with a free SSL certificate using Let’s Encrypt, you should move on to How To Secure Nginx with Let’s Encrypt on Ubuntu 20.04.

As someone who has set up many web servers before (now!), I know that I can use Let's Encrypt to set up an SSL certificate. But back when I started reading these guides, that is the kind of knowledge I didn't have. Here, the author introduces that you can use a tool called Let's Encrypt to add HTTPS to your domain and links to a guide you can follow. Use of the word "free" is appropriate here too since some sites charge for SSL certificates; a beginner may not know that you can get free certificates.

My conclusion

I have a bit of a soft spot for Digital Ocean's documentation because it is among the first technical documentation that I used when I was learning about basic systems administration. With that said, every time I have gone to their site I have been able to find material relevant to solving a problem. I have spent many hours learning with help from Digital Ocean's documentation.

There are some parts of their site I find a bit frustrating, like the links to "Popular Topics" in the sidebar and the amount of space that the page banner, navigation bar, and secondary navigation bar take up. But, the most important part -- the content -- is consistently well structured and well written.