Improving technical documentation - 5 tips for development managers

1. Don't write it in-house

You manage a staff of qualified software developers. You hired them for their expertise in software development. It might have been their extensive and expert knowledge of the programming language you are using, or their experience of the development platform and infrastructure, or possibly, but less frequently, their experience in the field of enterprise your company is active in. One thing is certain however, you did not hire them because they are great authors or experienced technical writers. So don't use them as such.

You wouldn't hire a technical writer and ask them to write code, so why would you think that the opposite will work? Creating good documentation is a specialist skill like any other.

In exactly the same way as you hire expertise in every other aspect of product development, hire expertise for producing and maintaining product documentation.

Basic rule: Get qualified staff to do your documentation.

2. Be clear on who it is for and what it is for

Very few products or services need only a single type of documentation and that list is limited to those products that are targeted solely at consumers AND that have a really intuitive user interface. They need documentation that helps even the most timid of users to start the product so that the intuitive user interface can start to work its magic. As consumer electronic become so proliferate and more and more user-friendly, we have all seen examples of this kind of documentation, and most often, it does the job. And the reason this kind of document is generally so successful is because its target group is well-defined and the purpose of the document is very clear. Two secrets of good documentation,

It is, of course, much more difficult to define the target group and the purpose of the documentation for more complex and complicated products, but it is, in the opinion of this writer, an absolutely essential task if you want to create good documentation. Somebody whose job it is to install and configure the software does not need to know how the software will be used on a daily basis. Yes, it might be "nice to know", but it is not essential for that person to do their job.

Basic rule: Define target group and purpose before starting.

3. Less is better

In my experience, in-house documentation created by development engineers usually contains way too much information. It is all too easy to see that the writer, or more likely writers, had written down just about everything they know about the software. In most cases, that is a lot, after all, who knows more about the software than the developers?

And therein lies the problem. Developers know so much about the software that they have great difficulty understanding what it is that the users have difficulty with. So because they are incapable of focusing on just what the target group needs in a particular situation, they include everything. This is in no way a criticism of software developers, that would be grossly unfair. It would be like criticising a doctor for not being able to conduct a symphony orchestra. Totally separate and unrelated skill sets.

Instead, think about what your target group really needs to know in their daily work situation and give them just that information in an easily accessible form.. Put other information in other documents.

Basic rule: One document per purpose.

4. Pay attention to detail

Most people I know become as irritated as I do when confronted by typographical errors in the newspapers. Line-breaks that cause "the" to be doubled, inconsistencies between the name of someone in the caption to a picture and that same person in the text, spelling mistakes, use of "were" instead of ''where", and so on. The list is long. I mention newspapers because that's where we see such errors most often. But other texts are not exempt and there the effect is probably more severe. For newspapers, the common reaction is "If they can't even get the text right, how can I trust what they write?". For a product, however irrational it may be, the fact is that people equate the quality of your documentation with the quality of your product. So if your documentation shows language errors that could easily have been avoided, people will think that the same could be true of your product. You don't release code without it being checked, so give your documentation the same treatment.

Basic rule: Make sure your documentation gets a language review at least once.

5. Be consistent and correct

I recently opened a user manual which had a file-name that included a product name, not an unusual thing. As I started to review the document I became confused about which product the manual was about. In the first four pages, two product names were used, neither of them the same as the product name in the file-name. I cannot stress enough how confusing, and potentially damaging (see point 4), this kind of inconsistency can be, not to mention how irritating it is.

A different type of inconsistency that is also very frustrating is when the names of things such as menu items, buttons, fields and similar are written in the documentation in ways that do not match what the user is actually seeing. This can happen very easily when the product is updated close to the launch or release date but the documentation is not. At least, this devalues your documentation. At worst, this can be so confusing to the user that they cannot get the product to work properly, and then they will call your help-desk, a cost-driving incident that could so easily have been avoided.

Basic rule: Include a factual review as part of the documentation development process.

Summary

There can be several other factors that affect the quality of the tecnical documnentation that your in-house deverlopers will produce, but in my opinion these five have the biggest effect.