Five Helpful Tips for Writing Documentation

Author by Megan Stoffel

Let’s be honest, no one really enjoys writing documentation when that point is reached in the project. But even something as simple as documentation can be improved with a couple of helpful tips! Recently, I’ve been working on some documentation for a client, and I thought I’d share some of the tips that I’ve found to not only be very helpful for the client, but for you as well.

  1. Start with the Images

The first thing I found to be very helpful, was to start with the images of the technology that you are documenting about. This way, everything that is being prepared to be explained can be visually seen, and details that might have been forgotten otherwise will be included. By adding the images first, you can map out exactly what you plan on explaining and fill in the gaps from there.

  1. Don’t Assume the Users Understand Everything

The second thing I realized was to not assume that the targeted audience for the document understands everything that is being explained. By using basic language to talk through the steps, less confusion and questions can be ensured in the future.

  1. Include a Table of Contents

A table of contents is a wonderful way to organize the document into sections. It creates a preview for what will be explained, as well as an outline where specific information can be easily found.

  1. Follow Your Own Instructions

Lastly, when the document is complete, go through and follow the instructions you’ve written. This way, any information that might have been left out can be found and included.

  1. Have Someone Unfamiliar with the Technology Read Through the Instructions

Having someone unfamiliar with the technology reading through the instructions can help determine where the language might be confusing. When writing about something that seems so familiar to you, it can be hard to determine what the users encounter when using the technology. Having a second pair of eyes is always good to help catch any mistakes, but someone unfamiliar with how it was built or created can be especially helpful for finding any spots where a concept was assumed to be understood.

While documentation isn’t the most glamourous task in the world, hopefully with these tips you can create more flawless documentation.

Tags in this Article