User documentation: what makes it bad and how to fix it

Software documentation is just a collection of articles, but even they can make you crazy. First you look for the right instruction for a long time, then you understand the obscure text, do as it is written, but the problem is not solved. You are looking for another article, you are nervous ... After an hour you spit on everything and leave. This is how bad documentation works. What makes it so, and how to fix it - read under the cut.

Our old documentation had many flaws. For almost a year now we have been processing it so that the scenario described above does not concern our customers. See how it was and how it became .

Problem 1. Incomprehensible, poorly written articles

If it’s impossible to figure out the documentation, what's the point? But no one writes obscure articles on purpose. They are obtained when the author does not think about the audience and purpose, pours water and does not check the text for errors.

• The audience . Before writing an article, you need to think about the level of preparation of the reader. It is logical that in the article for the beginner you should not skip the basic steps and leave the technical terms without decryption, and in the article on a rare feature that is necessary only for the pros, chew on the meaning of the word PHP.
• Purpose . Another thing that you should think about beforehand. The author should set a clear goal, determine the useful effect of the article, decide what the reader will do after reading it. If this is not done, a description will be obtained for the sake of description.
• Water and bugs . A lot of unnecessary information and clericalism, errors and typos interfere with perception. Even if the reader is not a grammar nation, negligence in the text can push him away.

Consider the tips above, and the articles will become clearer - guaranteed. To make it even better, take on our 50 questions when working on technical documentation .

Problem 2. Articles do not answer all questions

It’s bad when the documentation does not keep up with the development, does not answer real questions, errors in it have not been fixed for years. These problems are not so much the author, as the organization of processes within the company.

The documentation does not keep up with the development

The feature is already in the release, marketing plans to cover it, and it turns out that the new article or translation is still not in the documentation. Because of this, we even had to postpone the release. You can ask everyone to hand over the task to technical writers on time, but this will not work. If the process is not automated, the situation will be repeated.

We have made changes to YouTrack. The task of writing an article about a new feature falls to the technical writer at the very moment when they begin to test the opportunity. Then marketing learns about her in order to prepare for promotion. Notifications also come in the corporate messenger Mattermost, so it’s simply impossible to miss news from the developers.

The documentation does not reflect user requests

We used to work like this: a feature came out, we talked about it. We described how to turn it on, off, make fine settings. But what if the client uses our software in a way that we did not expect? Or is he making mistakes that we haven’t thought of?

In order for the documentation to be as complete as possible, we advise you to analyze support requests, questions on thematic forums, and queries in search engines. The most popular topics should be passed on to technical writers to supplement existing articles or write new ones.

The documentation is not being improved

It’s hard to do right away perfectly, anyway there will be errors. You can rely on the feedback from customers, but they are unlikely to report every typo, inaccuracy, incomprehensible or unknown article. In addition to customers, employees read the documentation, which means they see the same errors. It can be used! It is only necessary to create conditions in which it will be easy to report a problem.

We have a group on the internal portal where employees leave comments, suggestions and ideas on the documentation. Support needs an article but doesn't it? Did the tester notice an inaccuracy? Partner complained to development managers about mistakes? Everything in this group! Technical writers fix something right away, transfer something to YouTrack, take something to think about. To keep the topic quiet, from time to time we recall the existence of the group and the importance of feedback.

Problem 3. You have to look for the right article for a long time

An article that cannot be found is no better than an article that is not. The motto for good documentation should be “Easy to search, easy to find.” How to achieve this?

Streamline the structure and determine the principle of choosing topics . The structure should be as transparent as possible so that the reader does not think “Where can I find this article?” To summarize, there are two approaches: from the interface and from tasks.

1. From the interface. Content duplicates sections of the panel. So it was in the old ISPsystem documentation.
2. From tasks. The titles of articles and sections reflect the tasks of users; headings almost always contain verbs and answers to the question “how to do”. Now we are moving to this format.

Whichever approach you choose, make sure that the topic meets the needs of users and is covered so that the user accurately resolves his question.

Establish a centralized search . In an ideal world, the search should work even when you are saddened or mistaken with the language. Our search in Confluence cannot please this yet. If you have many products, and the documentation is general, adapt the search to the page on which the user is located. In our case, the main search works on all products, and if you are already in a specific section, then only on the articles in it.

Add content and breadcrumbs. It is good when there is a menu and breadcrumbs on each page - the user's path to the current page with the ability to return to any level. In the old ISPsystem documentation, you had to exit the article in order to get into the content. It was inconvenient, so in the new we fixed it.

Arrange links in the product . If people come in support from time to time with the same question, it is reasonable to add a hint with its solution to the interface. If you have data or understanding at what point the user is faced with a problem, you can also notify him by newsletter. Take care and remove the load from support.


To the right of the pop-up window is a link to an article about configuring DNSSEC in the ISPmanager domain management section

Configure cross-references within documentation. Articles that are related should be “linked”. If the articles are a sequence, be sure to add forward and backward arrows at the end of each text.

Most likely, a person will first go to seek an answer to his question, not to you, but to a search engine. It's a shame if there are no links to documentation there for technical reasons. So take care of search engine optimization.

Problem 4. Outdated layout interferes with perception

In addition to bad texts, the design may ruin the documentation. People are used to reading well-made materials. Blogs, social networks, media - all content is presented not only beautiful, but also easy to read, pleasant to the eye. Therefore, you can easily understand the pain of a person who sees the text as in the screenshot below. There are so many screenshots and selections in this article that they do not help, but only interfere with perception (the picture is clickable). You should not make a longrid from the documentation with a bunch of effects, but you need to take into account the basic rules. Layout






. Define the width of the main text, font, size, headers and indents. Engage a designer, and to accept a job or do it yourself, read Artyom Gorbunov's book Typography and Layout. It presents only one of the views on the layout, but it is quite enough.

Allocations . Define what needs emphasis in the text. Usually this is the path in the interface, buttons, code inserts, configuration files, “Pay attention” blocks. Set what the selection of these elements will be and fix in the schedule. Keep in mind that the less excretion, the better. When there are a lot of them, the text “makes noise”. Even quotation marks create noise if used too often.

Screenshots. Arrange with the team in which cases screenshots are needed. There is definitely no need to illustrate each step. A large number of screenshots, including individual buttons interfere with perception, spoil layout. Determine the size, as well as the format of the selections and captions in the screenshots, fix in the regulations. Remember that illustrations must always be written and relevant. Again, if the product is regularly updated, keeping track of each will be difficult.

The length of the text . Avoid overly long articles. Fragment them into parts, and if not possible, add anchor-linked content to the top of the article. An easy way to make an article visually shorter is to hide the technical details needed by a narrow circle of readers under a spoiler.

Formats. Combine several formats in articles: text, video and images. This will improve perception.

Do not try to cover up problems with a beautiful layout. Honestly, we ourselves hoped that the "wrapper" would save the outdated documentation - it did not work out. The texts had so much visual noise and unnecessary details that the regulations and new design were powerless.

Much of the above will be determined by the site that you use for documentation. For us, for example, this is Confluence. He also had to tinker with. If interested, read the story of our web developer: Confluence for a public knowledge base: change the design and set up language separation .

Where to start improving and how to survive

If your documentation is as vast as ISPsystem’s, and you don’t know what to grab, start with the most serious problems. Clients do not understand how to improve texts, make regulations, and train writers. Documentation is outdated - take on internal processes. Start with the most popular articles about the most sought after products: ask for support, see website analytics and search engine queries.

Let's say right away - it won’t be easy. And quickly, too, it is unlikely to succeed. Unless you are just starting and doing right right away. We know one thing for sure - it will get better over time. But the process will never end :-).