Advent of Technical Writing: Outlines

This is the seventeenth 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.

How do I get started with a technical guide? Great question! I like to start guides with outlines in one of two forms:

1. A few bullet points that note what I want to talk about, or;
2. A few headings that summarise the content I want to include in an article, in order of how they should appear in the guide.

Bullet Points

Writing a few bullet points in the document you are going to write in (i.e. a Google Doc, or whatever your editor of choice) helps you avoid having a blank page at the beginning. You have text, in front of your eyes, that can ground you. You can write down whatever points you want to make, in as much or as little detail as you want. These points can help you get started. When you start writing, you might find that your bullet points are easier to expand than if you were writing only from the knowledge in your head.

I sometimes start blog posts with a few bullet points. I do this a lot when I am not yet ready to write a post but I have a few ideas that I want to remember. Here are the bullet points I wrote for this guide as an example:

• Bullet points, or a document structure
• Helps with thinking about what you want to say and in what order
• You can always change later

These bullet points are rough and may be difficult to interpret since you didn't write them. Notes always make more sense to the author. Above, all bullet points are concise and express an idea that I wanted to mention. I didn't go into too much detail, but you could do so in your bullet points. Notice how that first bullet point was fleshed out into the first few paragraphs of this post. I will explore the themes in the other two bullet points later in this post

With the above bullet points, I validated that I had topics to talk about, which helped me build more confidence. I also knew that I wasn't starting from a blank slate. This is a big deal. Starting from a blank page can be intimidating.

Headings

I also find writing example headings useful. I write the headings in the order they will appear in a document. For example, here are the headings that I wrote for my guide on deploying vision models offline:

1. What is Roboflow Inference?
2. Preparation: Upload or Train a Model on Roboflow
3. Step #1: Set Up Roboflow Inference
4. Step #2: Run a Vision Model on an Image
5. Step #3: Run a Vision Model on a Webcam
6. Conclusion

(I don't have the raw headings I wrote, so these are from the article itself. My raw headings were not too far from this.)

By writing these headings, I already had text on the page. I was also able to build a better picture about what I wanted to talk about and in what order. I knew I needed to include:

1. An introduction to the solution (Roboflow Inference).
2. Preparatory information, which in this case was uploading or training a model to our platform.
3. How to set up Inference.
4. How to use Inference.

With these headings ready, I could get to work, knowing I already had something of an outline on the page. As I wrote, I could spend less time thinking about what section I was going to write next, and more time on expanding each title into a full section. Often, my titles change. I realise I need to add more sections, or remove some. That is okay. What matters is getting started on a piece; this technique has helped me do so.

That's it for today's technical writing tip! Join me tomorrow for another tip.