Your 8 Point Checklist For Perfect Technical Documentation

It’s benefits for organisation and efficiency… It’s a necessity for attracting further investment and scaling up…

(That’s just the York notes, here’s an article that explains it fully for you):

So, we get it, Greg, it’s important… Now, what can we do actually about DO about it?

What I’ll give you here is a simple 8 point checklist you can work through to ensure that your documentation is the best it can be and to set those precious foundations for the future success of you and your business!

Buckle up!

1. Define Audience and Objective

Is it being written for employees? Developers? The users?

Once you know your audience, what’s the objective? What is the document being written to help them DO? Always keep that at the front of your mind when you are writing it.

Your audience can also be a factor in the language and tone you use when you’re writing it.

Remember the golden rules here: ‘just enough string to wrap the parcel’ and ‘never assume’- write everything you need, but no more, and don’t make assumptions about the reader’s knowledge (this is particularly important for documents servicing the end-user!)

2. Do Your Research

Once you know your audience and you know the purpose, then you need to establish the scope of the work (and if you have any old resources to bring to the table or if you’re starting from scratch).

3. Create a Documentation Plan

  • An outline of your topic and sub-topics.
  • What software and tools you’ll need to manage it.
  • Timelines for delivery.

4. Structure and Design

The contents may be the most important thing but how they look and how they are organised is important too. Remember your reader!

Use templates for consistent on-page design.

Make sure the structure is logical.

Who am I writing for?

Considering which questions you will be answering for them – and when – helps give your documents a logical flow and makes for easier navigation and a better user experience. This is important throughout development but, again, even more so for your end-users.

5. Write It!

  • Start with an outline for each document: what to include and when.
  • Again, put your audience and your objective at the front of your mind. ‘Just enough string to wrap the parcel’ and ‘never assume’…
  • Then get down to it. The first draft is basically about getting it all out on the page. “Show up and throw up”. Once you have that done you have something to work with.

6. Review It

First yourself (or whoever is responsible for writing it), then by your peers or superiors. Check it’s clear. Check it follows a logical flow. Check it’s accurate.

Does it include everything you needed it to aka does it meet its objective?

Then review it some more.

7. Test It

Okay, you’re almost there! But there are a few last quality-control checks needed to identify any organisational or usability issues that may have slipped through the cracks.

Have someone work through the process, first with a navigational audit (checking the flow is logical, the information needed is all there and any links are present and correct) then checking for any usability/UX issues.

8. Publish It

Once you and your team agree it’s all complete and accurate, you’re ready to publish!

And I’d love to tell you that was it. I’d love to. But even when your documents are in the hands of your grateful and happy customer, the works not over yet.

These documents are dynamic and will go through many changes during the life cycle of the product. You need to establish a protocol for who is responsible for any changes and when. Out-of-date documents are useless documents! A maintenance schedule will help you keep on top of this.

And there you have it.

Lack of adequate planning is THE number one reason most new businesses fail and your documentation is the very framework of your planning. Who does what and when.

If you follow this checklist you are giving yourself and your business the very best chance to be one of the success stories, not the cautionary tales.

Greg Whitfield.