The purpose of technical documentation

Please send any completed exercises to [email protected]

Module 1 - Exercise 1b

Do let us know by email what prompted you to take this course, and what your current role in work is.

Extra content for you

When you subscribe to the Cherryleaf newsletter, each month you’ll get news, advice and information aimed at making you a better technical and business communicator.

To subscribe, use the form below.
Your details won’t be shared with anyone, and you can un-subscribe at any time:

module1- handout slides.pdf

Module 1 transcript

-- Slide --

Welcome to the first module in this course.

In this module, we will look at the purpose of technical documentation.

So we are going to look at issues around:

  • Defining the audience
  • The benefits of communicating this type of information effectively, and
  • Why it’s important to know your audience

At this point, we won’t dive into defining what is meant by technical documentation too much.

In essence, we’re talking about content that helps users of a product should they get stuck, content that prevents them getting stuck in the first place, or advises them on completing a task more efficiently.

It’s usually instructional content.

Sometimes it’s look up, reference, information, and other times it can be explanatory information about a concept or process.

-- Slide --

Let’s start off with a fundamental question: Why bother with technical documentation at all?

What is the purpose of it?

-- Slide --

When we did a survey some years ago and asked documentation manager this question, there were a number of answers given.

For many, it was about the users and making them effective at what they do.

Helping them when they get stuck.

Reducing the amount of errors and improving their abilities.

Another key factor related to cost.

Reducing the costs for the business especially the support calls.

There were other aspects around its value for marketing, SEO purposes and for increasing sales

And we’ll look at some of those in more detail.

-- Slide --

So let’s look at its role in reducing costs.

One of the key reasons for having documentation is to reduce costs, especially to support.

You will see reports from companies, such as Mindtouch, stating the cost of a support call to a support desk can range from about $30, up to about $150.

So if technical documentation can avoid the need for someone to make a support call, then that is a saving.

It can also help in reducing the costs of rejected products.

It may be that people are saying a product doesn’t work or they are breaking it, because they are using it incorrectly.

Or it is too difficult.

By having technical documentation, we can get users to understand that the product isn’t broken, but they need to use it in the proper way.

There are other ways that it can save costs, which are harder to quantify, such as the minimisation of risk.

If users are doing things incorrectly, and that could result in an outcome, a disaster that’s expensive or dangerous, then technical documentation, procedures, can be a good way to minimise that risk.

It can also lead to better and more effective users, more productive users, by stating the right, most efficient way to do something.

-- Slide --

Another reason for having technical documentation can also be to increase revenues.

It is not the main reason for having technical documentation.

But there can be benefits.

For some products they use a "try before you buy" sales model.

Where users use a free version before they move up to a chargeable version.

It is important for organisations that the users can get up to speed on using the product quickly.

If they get stuck and give up using the product at an early stage, the organisation may not have had any money from that user.

So giving users the right information so they know what to do and how to do things is quite important.

If this content is on a website and it is included in Google search engine results, then it can play an important factor in the pre-sales process.

Google and other search engines favour this type of information rich content, and they rank it highly.

Prospects also like it, as they find it more trustworthy than marketing copy.

Web-based information can also provide, through web analytics, useful information on the number of people reading your content, the demand for technical documentation

It might improve the perceived quality of the product, as well.

People expect that with a high quality product you got good user documentation.

If you don’t have it, you may struggle to be seen as that type of product.

Obviously, the more capable your users are, the more people you have who are good at using it, then the more likely you are to have customers who would recommend you or become evangelists for your product

And indirectly that can lead to more sales as well.

-- Slide --

It is critical you know your audience before you start writing, and be aware what it is that they want.

What it is that they need.

You can do that by defining, for each deliverable you provide, which audience it is targeted at.

It may be that you have more than one audience:

  • Beginners
  • Power users
  • Administrators

You may have people trialling the product.

That try before you buy model.

--- Slide --

In summary, it is important when starting a project and writing documentation to be clear what is the purpose of it.

And who is the audience for each document.

Complete and Continue