Three examples of Technical Writing outlines

This lesson provides you with some real examples of outlines for specific documents. We encourage you to use these example outlines to guide you as you create the outline for your next piece of technical writing.

Bug report

It is important that you are clear on how to write a bug report because bugs happen! If you find a bug, but are not able to log it in a way that is clear to the person responsible for fixing it, the bug will not be fixed and the experience of your product will not be improved. 

If you find a bug but cannot log it clearly for the person fixing it or if the bug is not reproducible, the bug will not be fixed, and your product experience will not improve. The developer must be able to visualize the situation, or else they will be unable to fix the bug.

Bug reports should be as concise and get straight to the point with as few words as possible. 

The best way to outline for this kind of report is to put yourself in your fellow developer's shoes and ask yourself questions from their point of view. 

Take a look at the following scenario:

On Tuesday, after a recent merge, the website's search is not bringing up the correct information when prompted. You decide to write a live site bug report. To do so, you would organize the necessary information as follows:

• Your name

• The product or location of the bug

• If applicable, the product version should be included

• Platform used at time of bug

  • Mag, PC, etc.

• Operation system used at time of bug

  • Windows, Mac OS, etc.

• Impact of bug on the product

• Priority of bug

  • This will depend on the bugs's impact.

• Assigned developer

• URL or page where bug was found

• Summary of the bug found

• Description of the bug

• Visual depiction (if applicable)

One-pager

One-pagers are written to provide an overview of a service, product, and so on. Many one-pagers follow a specific format or structure, which allows you to focus only on adding relevant information. 

Take a look at the structure below. This is just one possible way to structure a one-pager.

• Prerequisites

• Introduction

• Current scenario

• Assumptions

• Goals

• Impact (Leading indicators)

• Discussion

  • RICE score

  • How metrics will be measured

• The problem we want to solve

• Competitive analysis

• Solution 1

  • Scenarios

  • MoSCoW prioritization

• Solution 2

  • Pros

  • Cons

• Constraints/caveats and their resolutions

• MVP (minimum viable product)

  • GA events

  • What this looks like in the product

  • Workflow

  • Future roadmap

Technical article

An outline for an article takes an approach slightly different than those in the outlines shown above. Unlike those outlines, articles do not have any specific format that they should follow, and there is less of a formula to ensure that all required information is included. 

This makes things a bit trickier, but it also gives you the freedom to play around with the format.

Take a look at the following scenario:

You recently solved a challenging bug at work that you want to share with others via your website or Educative Answers. Your goal is to present the problem and the solution clearly and logically so that readers can recreate the error if they encounter it. 

Create your outline by copying and pasting the questions below into a separate document. Then answer each question. Once you are done answering each question, you will be nearly complete.

To outline:

• What is the focus of the article? Is it a problem? Is it a process that needs to be explained and understood?

• What is the answer/solution to this problem?

  • If the solution requires a step-by-step solution, write the steps out. Graphics can also be a great way to walk readers through the situation or process with you.

• What knowledge should the readers of your article leave with?

• Will readers need any pre-requisite knowledge to understand this article? If so, what?

Once finished, you should have the general structure of your article:

• Problem statement + any required background information

• Answer to the problem

• Written out solution with any necessary explanation/graphics