How To Write a Proposal and Outline for a DigitalOcean Community Tutorial

Introduction

So you want to write a tutorial for DigitalOcean! The DigitalOcean Editorial Team is here to support writers like you: developers and engineers who want to share their knowledge with others in the Community.

Because DigitalOcean can’t accept every tutorial that’s submitted to us, we ask to see a proposal before we approve you to begin writing. We don’t want you to write the whole tutorial before you know whether you’re accepted, so we ask for a detailed outline. That way, we get a good idea of what you want to write about, and we can offer you some feedback before you start writing. That’s the best time to make structure changes to your article, because it’s much easier to revise an outline than it is to revise a draft. With a good outline in place, you have a framework that makes the writing process go more smoothly.

In this article, you’ll see how to craft a proposal and outline for your tutorial idea. You’ll do some preparation first that will help you shape the content, you’ll decide on the goal that you want readers to achieve, and then you’ll define the steps that will get them there. The writing process is iterative, so you may find yourself returning to previous steps, but this framework will help create the outline.

Step 1 — Defining Your Focus

The first thing to decide on is what you want to write about. Often, you’ll start this idea with a single noun, for example: Nginx, or Helm, or React. Next, find the verb that goes with the noun: what do you want users to do with the product? Or to put it another way, what’s the learning outcome for the reader? At this stage, you’ll shift the focus from the writer to the reader. Instead of “what do I want to write about?” the question becomes “what does the reader want to accomplish?” Finding the right verb will answer that question. Verbs like “learn” or “understand” aren’t good topics for a tutorial, because they don’t have a measurable outcome. Instead, consider verbs like these:

• Install
• Create
• Configure
• Integrate
• Deploy
• Monitor
• Test
• Secure
• Automate
• Troubleshoot

Almost all DigitalOcean tutorials start with the words “How To,” which gives you a lead-in to choosing a good verb. The following are good tutorial titles that use the nouns with appropriate verbs:

• How To Configure Nginx as a Web Server and Reverse Proxy

• How To Install Software on Kubernetes Clusters with the Helm 3 Package Manager

• How To Manage State with Hooks on React Components

This gives you a clear statement of the learning goal for the reader, which should also help you define your title. Both of these are pieces of information we’ll ask for in your proposal.

Once you have the topic defined properly, you can turn your attention to who you’re writing for.

Step 2 — Deciding on the Audience

The next thing to consider when planning a tutorial is who is going to read it. Who will benefit most from the tutorial, and how much do they already know? How much they already know will determine how much background information you need to provide, which affects how long the tutorial will need to be.

For example, the tutorial Initial Server Setup with Ubuntu 20.04 assumes very little background knowledge. It explains what root is, and how SSH keys work. This is an appropriate audience for readers setting up a server for the first time.

The tutorial How To Progressively Deliver Releases Using Flagger on DigitalOcean Kubernetes assumes a much more experienced reader. It assumes that readers are familiar with Kubernetes, Helm, and Nginx, and already have a cluster configured to use all of these technologies. This allows the author to skip over configuring those products, and concentrate on Flagger, which is the subject of the tutorial.

For DigitalOcean tutorials, a narrow audience is usually better than a broad one. If you’re writing about how to configure Kubernetes load balancing settings, you may think the audience should include everybody who uses Kubernetes, but you’ll have a more useful tutorial if you focus the audience to just Kubernetes admins who have enough clusters and enough traffic to require fine-tuning the load balancers. In other words, a more advanced audience.

That doesn’t mean that your tutorial won’t have broad appeal, and you can provide additional context to appeal to readers at other skill levels. However, the planning stages will be easier if you keep the audience narrow.

Defining your audience will give you an idea of how much content you need to cover, or in other words, the scope.

Step 3 — Deciding on the Scope

As with the audience, the scope for a DigitalOcean tutorial should be narrow. Try to keep your focus on a single task. A tutorial on “How To Deploy a Node Application with a React Front End and a MySQL Data Store” has a lot of components, and a lot of steps. We’d rather see a tutorial on how to deploy a Node application. Once the first tutorial is successfully published, you could propose another using the first tutorial as a prerequisite, and build to a more complex solution that way.

A narrow scope is also preferable because we want readers to be able to reproduce the steps successfully. You could write a tutorial about monitoring that involves six different servers, but the reader would need to set up that many Droplets, which could be inconvenient or expensive. If you can accomplish the same goal with just two Droplets, readers can extrapolate to a larger network.

Similarly, try to avoid tutorials that require multiple different technologies. A tutorial on (for example) “How To Deploy a Flask application with TravisCI and Grafana monitoring with Nginx on Debian,” would only be useful to readers using all of those exact technologies. That limits the tutorial’s lifespan, if one of those technologies gets replaced or is no longer supported. The exception to this guideline is tutorials that are specifically intended to demonstrate the use of a specific tech stack, such as LAMP or Elastic.

With the limits of the tutorial defined, you can start to create the framework for your tutorial with an outline.

Step 4 — Brainstorming the Tasks

Now that you know what you want to write about, and who to write it for, you can start putting together an outline. The first part of that process is to brainstorm what’s involved with the problem you’re trying to solve. Think of the overall task involved, and the individual processes you might take. For example, if you were writing a tutorial on How To Install Nginx on Ubuntu, you’d include a step for sudo apt install nginx, but there are other considerations as well. In this tutorial, the author has included these additional steps:

• Adjusting the firewall to allow access

• Verifying the web server

• Managing the process

• Setting up server blocks

Those steps aren’t strictly part of the install nginx process, but they are necessary for a proper Nginx installation, which is why a tutorial adds value over the basic documentation. Think through the process to identify these additional tasks, and write them down as you think of them. You don’t have to have them in order at this time; you’re just defining the content to cover.

This may take some time. For example, you may not think of adjusting the firewall right away, because you usually have your firewall configured properly. When you think of it, write it down. Be inclusive at this step. Think about tasks that may be “nice to have” or not strictly related. Once you’ve thought of everything you’d want to include, it’s time to organize.

Step 5 — Organizing the Tasks into an Outline

The previous step gave you a list of possible tasks to include in the tutorial, so the next part is to organize them. Some of these will be clear, because of the flow of operations: You have to run the install nginx command before you can test the results, so the installation step has to come first. Some steps might not be as obvious: should readers configure the firewall after installation, or before? Think about each step in terms of the learning goal for the reader: How does this step help them progress toward the overall goal? Some steps won’t have a specific place where they need to happen, and that’s fine.

Make sure each step of the process accomplishes something tangible, meaning each step should have a useful verb in it. If you wrote “Understanding how firewalls work” as a step, that doesn’t accomplish something demonstrable. The step “Configuring the Firewall” leaves the reader with something concrete: a firewall that blocks most traffic, but admits some.

You may have written down some steps that are outside the scope of the tutorial. For example, you need an Ubuntu server before you can install Nginx on it, but that’s covered in another tutorial, so you don’t need a separate step for it. In this case, you can add “set up Ubuntu 20.04 server” to the prerequisite list, along with a link to the existing tutorial. Again, remember the learning goal you defined in Step 1, and let that be your guide as to whether the steps are in scope or not.

Other steps may be too advanced to be in scope. You may want to install Nginx to use it as a reverse proxy, but that setup is separate from installation, and is better covered in a separate tutorial. In our example tutorial, the author recommends setting up server blocks, but notes that it’s a recommendation, not a required part of the installation.

Finalize your outline by adding some detail about each step. Tell us in a few words exactly what the reader will do, why each step is important, and how it relates to the next. For the firewall step, you could add “Readers will use ufw’s Nginx HTTP profile to allow only traffic on port 80. This is a standard configuration for a public-facing web server.”

Step 6 — Avoiding Outline Traps

Your outline serves two purposes: It serves as a framework that will make the writing process easier, and it will let the DigitalOcean Editorial team know what you’re planning to write about, so they can decide whether to accept it for publication. Here are a few things we commonly see in outlines that we recommend avoiding for the best chance of acceptance:

• Background steps: If you have a step where the reader doesn’t do anything concrete, or a step that just provides background, look for someplace else to put that information. If you want to provide some background on what a technology is commonly used for, that can go in the Introduction section of the tutorial. If you’re explaining why readers are taking a step, consider using “just in time” explanation. For example, instead of explaining the theory behind firewalls first, have the reader use the commands to configure the firewall, and then explain exactly why they used those specific commands. Readers learn better when they have something hands-on to link with the theory.

• Unexplained steps: DigitalOcean editors have a lot of experience with various technologies, but we’re not experts on everything. Adding some explanation to each step in your outline will help us understand how the steps fit together to achieve your goal. A step like “Setting up a User” might not be clear by itself, but you could add “The database service requires a dedicated user with specific permissions, for security purposes. In this step, readers will create that user and set the permissions.” That way, we’ll know why this step is needed.

• Cloning a repo: Many outlines have a Step 1 that asks readers to clone a repo to get a sample project to deploy in the tutorial. We avoid this pattern for several reasons. First, we need to ensure the repo is available for the life of the tutorial. (If a repo is needed, we’ll clone it to the DigitalOcean Community site and host it here.) Second, we don’t ask readers to run code we haven’t completely explained, for security reasons. Third, we treat every block of code as a learning opportunity, even if it’s not directly related to the topic of the tutorial. If your project includes a CSS file that’s too complex to explain without distracting from the tutorial, consider simplifying the CSS. Keeping the sample project to the minimum needed for the tutorial allows you to keep the focus where it belongs.

• Overly long steps: Sometimes you’ll have a step that includes other subordinate tasks. For example, you might have a step that requires serializing information on the server, transmitting it to the client, and then deserializing it before rendering. If you discover that your step would benefit from subheadings, that’s a sign you should break up the step into two or more smaller steps. Your editor can help advise on this issue.

Conclusion

In this tutorial, you’ve done the pre-writing steps necessary to define your tutorial and give it focus. You refined the idea, identified the audience and scope, brainstormed the necessary steps, and finalized the outline. This gives you a strong foundation from which to begin writing, and also provides the information that our editors need to decide whether to accept your tutorial for publication. It’s normal for outlines to change during the writing process, either because of suggestions from your editor, or because of realizations you have while writing. Don’t think of the outline as unchangeable, but rather a framework to keep you on track.

For more information and guidance on the writing process, we have a variety of resources to help you. See our Technical Writing Guidelines, Technical Recommendations and Best Practices, and Tutorial Templates.