Generating good technical documentation, 5 tips for it-development teams

1 Foreword

It is a common organisational situation that the development team is given responsibility for the documentation of a product. However, documentation is hardly ever high up on the list of priorities. That can often lead to the task being given, much too late, to people within the team, but that have little experience of documentation

Here are five tips to help you make good documentation anyway.

1. Know who and what it is for

Very few products or services need only a single type of documntation and that list is limited to those products that are targeted solely at consumers AND that have a really intuitive user interface. Such products might only need documentation that helps the most timid of users to start the product so that the intuitive user interface can start to work its magic. As consumer electronics 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.

It is absolutely worth taking the time to clearly define which target groups will be needing documentation and what that documentation should cover before starting to write. Not only will the documentation be much better, but it won’t take as long to produce as its purpose is clearly defined.

Tip 1: Define target group and purpose before starting.

2. 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 users have difficulties with. So, because they are unable to focus on just what the target group needs in a particular situation, they include everything they can. 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.

Tip 2: One document per purpose.

3. Pay attention to detail

Most people I know become as irritated as I do when confronted by typographical errors in the newspapers, or in any document for that matter. 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 the 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.

Tip 3: Make sure your documentation gets a language review at least once.

4. 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 devastating 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.

Tip 4: Include a factual review of the documentation as part of the development process.

5. 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.

Tip 5: Get documentation experts to do your documentation.

Afterword

This article was written by Paul Gratwick, an experienced documenter and owner of Wordsmyth AB, a Swedish company that works with documentation and content. See wordsmyth.se.

Do not hesitate to get in touch if you have any comments or questions. My mail address is paul.gratwick@wordsmyth.se or contact me through LinkedIn.

4