Software documentation is just a collection of articles. But even they can get mad. First, you look for the right instruction for a long time. Then you understand the obscure text. You 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.
There were many flaws in our old documentation. For almost a year now, we have been reworking it so that the scenario described above does not concern our customers. look, и .
Problem 1. Incomprehensible, poorly written articles
If the documentation is impossible to understand, what is the point of it? But no one writes incomprehensible 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.
- Audience. Before writing an article, you need to think about the level of preparation of the reader. It is logical that in an article for a beginner, you should not skip the basic steps and leave technical terms without decoding, and in an article on a rare feature that only pros need, chew on the meaning of the word PHP.
- Goal. Another thing to think about ahead of time. The author must set a clear goal, determine the useful action of the article, decide what the reader will do after reading it. If this is not done, you will get a description 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 Nazi, sloppiness in the text can turn them off.
Consider the tips above, and the articles will become clearer - guaranteed. To make it even better, take advantage of our .
Problem 2. Articles do not answer all questions
It’s bad when the documentation does not keep up with development, does not answer real questions, and errors in it are not corrected for years. These are problems not so much of the author, but of the organization of processes within the company.
Documentation fails to keep up with development
The feature is already in the release, marketing plans to cover it, and then 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 turn the task over to technical writers on time, but it won't work. If the process is not automated, the situation will repeat itself.
We've made changes to YouTrack. The task of writing an article about a new feature falls to the technical writer the moment the feature is tested. Then marketing learns about it in order to prepare for promotion. Notifications also come to the Mattermost corporate messenger, so it's simply impossible to miss the news from the developers.
Documentation does not reflect user requests
We used to work like this: a feature came out, we talked about it. Described how to turn it on, turn it off, make fine adjustments. But what if the client uses our software in ways we didn't expect? Or does it have bugs that we didn't think about?
To make the documentation as complete as possible, we advise you to analyze support requests, questions on thematic forums, queries in search engines. Give the most popular topics to technical writers to add to existing articles or write new ones.
Documentation not updated
It is difficult to do it right away, mistakes will still be. You can rely on feedback from customers, but it is unlikely that they will report every typo, inaccuracy, incomprehensible or not found 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 for documentation. Support needs an article but doesn't have one? Did the tester notice an inaccuracy? Did the partner complain to development managers about mistakes? Everyone in this group! Technical writers fix something right away, transfer something to YouTrack, take something to think about. To keep the topic alive, from time to time we remind you of the existence of the group and the importance of feedback.
Problem 3. You have to search for the right article for a long time
An article that cannot be found is no better than an article that does not exist. The motto of good documentation should be "Easy to search, easy to find". How to achieve this?
Arrange 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.
- From the interface. The content duplicates the sections of the panel. So it was in the old ISPsystem documentation.
- From tasks. The titles of the articles and sections reflect the tasks of the users; headlines almost always have 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 is relevant to the user's needs and is covered in a way that the user will accurately address their question.
Establish a centralized search. In an ideal world, search should work even when you misspell or make a mistake with the language. Our search in Confluence so far cannot please us with this. If you have many products and the documentation is general, tailor the search to the page the user is on. In our case, the search on the main page works for all products, and if you are already in a specific section, then only for articles in it.
Add content and breadcrumbs. It's good when each page has a menu and breadcrumbs - the user's path to the current page with the ability to return to any level. In the old ISPsystem documentation, you had to leave the article to get into the content. It was inconvenient, so we fixed it in the new one.
Place links in the product. If people come to support with the same question over and over again, it is reasonable to add a tooltip with its solution to the interface. If you have data or understanding at what point the user is experiencing a problem, you can also notify them with a mailing list. And show care, and remove the load from support.
On the right in the pop-up window there is a link to an article about configuring DNSSEC in the domain management section of ISPmanager
Set up cross-references within documentation. Articles that are linked should be "linked". If the articles are in a sequence, be sure to add forward and backward arrows at the end of each text.
Most likely, a person will first go looking for an answer to his question not to you, but to a search engine. It's a shame if there are no links to the documentation there for technical reasons. So take care of search engine optimization.
Problem 4. Outdated layout interferes with perception
In addition to bad texts, design can ruin documentation. People are used to reading well-written materials. Blogs, social networks, media - all content is presented not only beautiful, but also easy to read, pleasing to the eye. Therefore, it is easy to understand the pain of a person who sees the text as in the screenshot below.
There are so many screenshots and highlights in this article that they do not help, but only interfere with perception (the picture is clickable)
You shouldn't make a long read of the documentation with a bunch of effects, but you need to take into account the basic rules.
Layout. Determine the body text width, font, size, headings, and padding. Involve a designer, and to accept the work or handle 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. Determine what needs emphasis in the text. Usually this is a path in the interface, buttons, code inserts, configuration files, Pay Attention blocks. Specify what will be the selection of these elements and fix in the regulations. Keep in mind that the fewer secretions, the better. When there are a lot of them, the text is "noisy". Even quotation marks create noise if they are used too often.
Screenshots. Agree with the team when screenshots are needed. It is definitely not necessary to illustrate each step. A large number of screenshots, incl. individual buttons, interfere with perception, spoil the layout. Determine the size, as well as the format of the highlights and captions on the screenshots, fix them in the regulations. Remember that illustrations should always match what is written and be up-to-date. Again, if the product is regularly updated, it will be difficult to keep track of each one.
Text length. Avoid overly long articles. Break them up into parts, and if not possible, add content with anchor links to the beginning of the article. An easy way to make an article visually shorter is to hide the technical details that a narrow circle of readers need 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 beautiful layout. Honestly, we ourselves hoped that the “wrapper” would save outdated documentation - it didn’t work out. There was so much visual noise and unnecessary details in the texts that the regulations and the new design were powerless.
Much of the above will be determined by the platform you use for documentation. For example, we have Confluence. He also had to deal with it. If interested, read the story of our web developer: .
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 onto, start with the most serious problems. Clients do not understand the dock - improve texts, make regulations, train writers. The documentation is out of date - take on the internal processes. Start with the most popular articles about the most in-demand products: ask support, see site analytics and search engine queries.
Let's just say it won't be easy. And it's unlikely to happen quickly either. Unless you are just starting out and doing the right thing right away. One thing is for sure, it will get better with time. But the process will never end :-).
Source: habr.com