50 documentation questions
No matter how hard the UX designer tries, a person from the street will not be able to figure out the interface of the spacecraft control without a hint. And not even from the street. Just because the rocket is big and there are many settings.
We make products simpler software for rockets, but still technically complex. We are trying very hard to ensure that the interfaces of the new versions are simple, but we realize that there will always be a user who does not understand something and goes into the documentation. Therefore, the dock should be, and in order not to spoil the impression of the product, it should be useful and convenient.
We have six products, the documentation to which from the very beginning of the company was written by the developers. For half a year we have been rewriting old ones and writing new articles . Under the cut - 50 questions that help us do it well. But first, a little introductory.
')
Making a good dock is tricky. Somewhere on it works a huge department of analysts, writers and editors, and somewhere the developers write to the dock (did - described).
We have two technical writers for six products with several versions. This is not enough, so product managers, testers, first-line support and marketing are working on the dock. They do not write articles, but they help to understand the product and tasks of the client, select a topic and collect information, check the content and design of the finished article. Together we make the dock better.
If you have a small department of technicians, engage employees from other departments. If they are not interested, list the arguments below. First supported, second and third marketer and product. So why is documentation important?
Define the goal . This is the most pain. To describe a feature simply for the sake of description or comment on the interface is not the goal. A goal is always a useful action. What should know and be able to user, admin or developer after reading the article? For example, create a website and link a domain to it, issue an SSL certificate, set up backups, etc. That is, solve your problem.
Know the audience . We divide customers into users, administrators, and developers. But this is not enough to create useful texts. To quickly understand the audience, you can go to the UX and the product, examine support requests and their answers to the right topic, listen to the first line calls, view the website and blog (marketing also writes the right things). And only after that start writing.
Check, edit and check again . Technical writers should do the initial check. After her one more. Then it’s worth connecting support, marketing and other departments to the test. Then you need to check with the manual on style and design - redpolitikoy. Someone from the side or another technician let him do the final reading. If you have an editor, then he will take over this stage.
Spread the article after publication . If the documentation is written, most likely someone needs it. Show it to the light and use to the maximum: translate, refer to the product, give it to marketing, support. Do not write to the table.
Working on the documentation, we repeated the same mistakes. They spent too much time checking the articles, and the guide, which seemed to be a panacea from the beginning, did not help, because the problem was in the approach and content. So that tech writers could bring the article to their own mind and quickly, we put all the questions in a list that we constantly asked (or forgot to ask) to them. Use if you are also writing to the dock.
1. Who am I writing an article for? Who is the future reader: user, administrator, developer?
2. What are the challenges facing him (jobs to be done)? Is there a description of the person?
3. What is the training level of this user? What does he already know? What is not obvious to him?
4. How can you explain this to a novice user and not annoy the advanced one by explaining elementary things?
5. What else should be explained to the user so that he understands the main content of the article?
6. Which section of the documentation is suitable for this article?
7. Is this article or part of it to be duplicated in other sections?
8. What articles should be referred to?
9. Maybe this article should be accompanied by a video instruction?
10. Do current users have issues related to the topic of the article?
11. How does support now explain what needs to be done?
12. Did the marketing department write articles and news on this topic on this topic? Can they "peep" the wording, structure, etc.?
13. Are there any sections dedicated to this topic on the site?
14. What did the UX and the product manager put into the script? Why did it do this?
15. How is this question described by competitors?
16. In what areas can you still see the best practices?
17. Has the goal of the article been achieved?
18. Will everything be understood by a more advanced user?
19. Will everything be clear to a novice user?
20. Is everything logical and consistent? There are no "jumps" and abysses?
21. Is the sequence of actions correct? Will the user be able to achieve the goal, following only this instruction?
22. We took into account all the cases / paths of the user?
23. Does the article fit into the selected section?
24. Are there any unreadable sheets of text? Is it possible to replace the circuit?
25. Are there long paragraphs?
26. Are paragraphs too short?
27. Are there too long lists?
28. Are there too nested difficult to read lists (those with more than two or three levels)?
29. Images enough?
30. Images are not too many? Do we illustrate too obvious steps?
31. If there are schemes, are they clear?
32. Tables are not difficult for perception?
33. Does the page look good in general?
34. Is everything done according to the guide?
35. Is the style of the rest of the documentation?
36. Any suggestions that you can simplify?
37. Are there complicated terms that need explanation?
38. Have clericals?
39. Have replays?
40. Doesn't hurt your ears?
41. Are there any typos, spelling errors and punctuation?
42. With hyphenation, paragraphs and sections, everything is in order?
43. Are all images signed?
44. Are the interface elements named correctly?
45. Are links everywhere? They work and lead where necessary?
46. The article has sections that are "catching up" in other articles? Are they decorated with macros so that changes in one article are automatically applied to others?
47. Should I refer to this article from other sections? If so, which ones?
48. Should I add a quick link to this article to the product?
49. Do I need to send a link to support, marketing or other departments?
50. Do I have to submit an article for translation?
This list can be printed and put on the desktop or hang on the wall. Or turn into a checklist. Part of the questions can be brought into the business process. Our, for example, is fixed in the overall development process in YouTrack. The task of documentation goes through different stages and departments; without written documentation, you cannot give a feature to a release.
We make products simpler software for rockets, but still technically complex. We are trying very hard to ensure that the interfaces of the new versions are simple, but we realize that there will always be a user who does not understand something and goes into the documentation. Therefore, the dock should be, and in order not to spoil the impression of the product, it should be useful and convenient.
We have six products, the documentation to which from the very beginning of the company was written by the developers. For half a year we have been rewriting old ones and writing new articles . Under the cut - 50 questions that help us do it well. But first, a little introductory.
')
Why documentation is important, and who should do it
Making a good dock is tricky. Somewhere on it works a huge department of analysts, writers and editors, and somewhere the developers write to the dock (did - described).
We have two technical writers for six products with several versions. This is not enough, so product managers, testers, first-line support and marketing are working on the dock. They do not write articles, but they help to understand the product and tasks of the client, select a topic and collect information, check the content and design of the finished article. Together we make the dock better.
If you have a small department of technicians, engage employees from other departments. If they are not interested, list the arguments below. First supported, second and third marketer and product. So why is documentation important?
- Support factor . The first and most obvious of the reasons. If the documentation is good, most customers will resolve the issue without contacting them. The remaining support will throw a link to the instructions or quickly go through it himself. Full documentation can be used to create chat bots. All this reduces the response time to customers, increases their satisfaction, and also reduces support costs.
- Factor of choice . Documentation affects the choice of the client along with the price, convenience, functionality. This is confirmed by our research and feedback from ISPmanager and DCImanager users . In this vein, the dock ceases to be a need for support, and becomes a competitive advantage, part of marketing.
- Loyalty factor . If the client left without understanding the dock at the start or in the process, this is a problem. Attracting a customer is too expensive to lose because of bad articles.
How to make good documentation
Define the goal . This is the most pain. To describe a feature simply for the sake of description or comment on the interface is not the goal. A goal is always a useful action. What should know and be able to user, admin or developer after reading the article? For example, create a website and link a domain to it, issue an SSL certificate, set up backups, etc. That is, solve your problem.
Know the audience . We divide customers into users, administrators, and developers. But this is not enough to create useful texts. To quickly understand the audience, you can go to the UX and the product, examine support requests and their answers to the right topic, listen to the first line calls, view the website and blog (marketing also writes the right things). And only after that start writing.
Check, edit and check again . Technical writers should do the initial check. After her one more. Then it’s worth connecting support, marketing and other departments to the test. Then you need to check with the manual on style and design - redpolitikoy. Someone from the side or another technician let him do the final reading. If you have an editor, then he will take over this stage.
About redpolicy
The editorial policy stipulates the presentation style (formal or informal), layout and design (screenshots, their sizes, styles of tables, lists), as well as controversial issues (e or e, spelling of terms). If you do not have such a document, be sure to do it, it reduces the time and brings order. For inspiration and understanding, see the report from the Yandex conference and examples of IBM or Mailchimp tutorials .
Spread the article after publication . If the documentation is written, most likely someone needs it. Show it to the light and use to the maximum: translate, refer to the product, give it to marketing, support. Do not write to the table.
50 questions for work on the dock
Working on the documentation, we repeated the same mistakes. They spent too much time checking the articles, and the guide, which seemed to be a panacea from the beginning, did not help, because the problem was in the approach and content. So that tech writers could bring the article to their own mind and quickly, we put all the questions in a list that we constantly asked (or forgot to ask) to them. Use if you are also writing to the dock.
Goals
1. Who am I writing an article for? Who is the future reader: user, administrator, developer?
2. What are the challenges facing him (jobs to be done)? Is there a description of the person?
3. What is the training level of this user? What does he already know? What is not obvious to him?
4. How can you explain this to a novice user and not annoy the advanced one by explaining elementary things?
5. What else should be explained to the user so that he understands the main content of the article?
6. Which section of the documentation is suitable for this article?
7. Is this article or part of it to be duplicated in other sections?
8. What articles should be referred to?
9. Maybe this article should be accompanied by a video instruction?
Information sources
10. Do current users have issues related to the topic of the article?
11. How does support now explain what needs to be done?
12. Did the marketing department write articles and news on this topic on this topic? Can they "peep" the wording, structure, etc.?
13. Are there any sections dedicated to this topic on the site?
14. What did the UX and the product manager put into the script? Why did it do this?
15. How is this question described by competitors?
16. In what areas can you still see the best practices?
Content check
17. Has the goal of the article been achieved?
18. Will everything be understood by a more advanced user?
19. Will everything be clear to a novice user?
20. Is everything logical and consistent? There are no "jumps" and abysses?
21. Is the sequence of actions correct? Will the user be able to achieve the goal, following only this instruction?
22. We took into account all the cases / paths of the user?
23. Does the article fit into the selected section?
Typesetting
24. Are there any unreadable sheets of text? Is it possible to replace the circuit?
25. Are there long paragraphs?
26. Are paragraphs too short?
27. Are there too long lists?
28. Are there too nested difficult to read lists (those with more than two or three levels)?
29. Images enough?
30. Images are not too many? Do we illustrate too obvious steps?
31. If there are schemes, are they clear?
32. Tables are not difficult for perception?
33. Does the page look good in general?
Literary editing
34. Is everything done according to the guide?
35. Is the style of the rest of the documentation?
36. Any suggestions that you can simplify?
37. Are there complicated terms that need explanation?
38. Have clericals?
39. Have replays?
40. Doesn't hurt your ears?
Final proofreading
41. Are there any typos, spelling errors and punctuation?
42. With hyphenation, paragraphs and sections, everything is in order?
43. Are all images signed?
44. Are the interface elements named correctly?
45. Are links everywhere? They work and lead where necessary?
Immediately after publication
46. The article has sections that are "catching up" in other articles? Are they decorated with macros so that changes in one article are automatically applied to others?
47. Should I refer to this article from other sections? If so, which ones?
48. Should I add a quick link to this article to the product?
49. Do I need to send a link to support, marketing or other departments?
50. Do I have to submit an article for translation?
This list can be printed and put on the desktop or hang on the wall. Or turn into a checklist. Part of the questions can be brought into the business process. Our, for example, is fixed in the overall development process in YouTrack. The task of documentation goes through different stages and departments; without written documentation, you cannot give a feature to a release.
Source: https://habr.com/ru/post/431456/
All Articles