In general, well-designed software documentation will have the following characteristics:

Easy to find!

You must have a meaningful title and short description text for your documentation. And it must be placed in a location where the user expects to find this documentation.

A well written documentation can first of all be found by the user! It’s often the case that I see, that so many technical communicators focus so much on the content itself, they forget that the MOST important thing is that your users need to FIND your documentation in the first place!

Does it really matter that you have no spelling mistakes in your topic if nobody is going to ever read that document?!


Specific for the target audience!

OK, I found my documentation. But wait - does it speak to me? Does it solve my problem?

If the user guide does not explain the solution to my problem, it is useless. Make sure you do not mix together the different target audience, so the user can feel safe and sound as to where he or she needs to search for answers!


Logically structured and organized!

What is the logic used to structure and organize the information? You must know that every time a user engages with your software documentation for the first time, there is a learning curve for this user. He or she needs to understand how the documentation is organized and written.

There are so many questions that the user needs to find an answer to, BEFORE he or she can even start reading your documentation: Do you have tasks and concepts on different pages? Where are the prerequisites for my task? Where are the steps of the task? Do you always put a heading Prerequisites on top of the prerequisites, or you put it always at the beginning of the task topic? Is the content in one single web page, a PDF file, multiple pages? How to search through your content? Where can I find more information? What if I have questions….

Make sure you apply a consistent and logical organization throughout your entire documentation, no matter which department has written it!


Uses Consistent Terminology!

Ah, that’s my favorite one: “Dear customer, use Product A which we have renamed to Product B but we still call it internally Project X…”!

Go figure what I want to tell you!

One of the most challenging tasks for the technical communicator is the creation and maintenance of the terminology database. It seems nobody likes to read a dictionary in their spare time! But your technical communicator role requires that you patiently put the attention in your team back to using consistent terminology throughout the entire documentation.

No exceptions allowed!