50 documentation questions
No matter how hard the UX designer tries, a person from the street will not be able to figure out the spacecraft control interface 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 make the interfaces of the new versions simple, but 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 and writing new articles.. Under the cut - 50 questions that help us do it well. But first, a little introductory.
Making a good doc is hard. 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, attract 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 calls to the first line, 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. For whom am I writing an article? Who is the future reader: user, administrator, developer?
2. What are the tasks 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 I refer to?
9. Maybe this article should be accompanied by a video instruction?
10. Do current users have problems related to the topic of the article?
11. How does support explain now what needs to be done?
12. Did the marketing department write articles and news on this topic on this blog? 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? 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. Everything is decorated on the guide?
35. Does 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 a replay?
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. All images are signed?
44. Are the interface elements named correctly?
45. Are there 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 make the interfaces of the new versions simple, but 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 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 doc is hard. 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, attract 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 support. 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 calls to the first line, 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
Редполитика оговаривает стиль изложения (формальный или неформальный), вёрстку и дизайн (скриншоты, их размеры, стили таблиц, списки), а также спорные вопросы (е или ё, написание терминов). Если у вас ещё нет такого документа, обязательно сделайте, он сокращает время и наводит порядок. Для вдохновения и понимания посмотрите доклад с конференции Яндекса и примеры руководств IBM или Mailchimp.
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. For whom am I writing an article? Who is the future reader: user, administrator, developer?
2. What are the tasks 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 I refer to?
9. Maybe this article should be accompanied by a video instruction?
Information sources
10. Do current users have problems related to the topic of the article?
11. How does support explain now what needs to be done?
12. Did the marketing department write articles and news on this topic on this blog? 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? 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. Everything is decorated on the guide?
35. Does 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 a replay?
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. All images are signed?
44. Are the interface elements named correctly?
45. Are there 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.