10 December 2018

Irina Varnina

Marketing manager

50 questions to ask while developing user and technical documentation

We at ISPsystem would like customers to use our products without any help or support. Right now we are creating intuitive interfaces for new versions of our products but they still are quite technically sophisticated. So, no matter how cool the interface is, there is always a user who doesn’t understand something and refers to product documentation. Therefore, the documentation must be there. And in order not to spoil the impression of the product, it must be both useful and convenient.
We have six products, developers themselves have been writing documentation to them for 13 years. For half a year we have been rewriting old articles and writing new ones. In this article, there is a list of 50 questions that help us improve our documentation. Let’s dive into it, but first, let us make some a few remarks.

Why documentation is important and who is to write it

Creating a good documentation can be tricky. It definitely will be. Bigger companies have huge departments of analysts, writers, and editors working on it, while in smaller ones developers themselves are to do this job.
We have two technical writers for six products with several versions. This is not enough, so product managers, QA technicians, support and marketing specialists are also involved. They do not write articles but they help to understand the product and tasks of the client, choose a topic and collect information, check the content and design the article. Together we make our documentation better.
If you have a small department or no technical writers at all, involve employees from other departments. If they are not interested, list the arguments below. The first one is for your support team, two others are for marketers and product managers.
  1. Support. The first and most obvious of the reasons. If the documentation is good, most customers will solve their issues without contacting support. If they do, a support specialist will give them a link or quickly follow the instructions themselves. Full documentation can be used to create chatbots. All this reduces the response time to customers, increases their satisfaction, and also reduces support costs.
  2. Decision making. Documentation influences the choice of the client along with the price, convenience, and functionality. This is confirmed by our research and feedback from ISPmanager and DCImanager users. In this vein, the documentation ceases to be a need for support and becomes a competitive advantage, part of marketing.
  3. Loyalty. If the client fails to understand the documentation at the start or later, this is a problem. Attracting a customer is too expensive to lose him/her because of bad articles, right?

How to make good documentation

Define the goal. This is the real pain. To describe a feature or comment the interface is not the goal. The goal is always about a useful action. What should user, admin or developer know and be able to do after reading the article? Create a website and link a domain to it, issue an SSL certificate, set up backups, etc. The article must solve user issues.
Know your 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 talk to UX department and product managers, study support requests and their answers to the right topic, listen to calls, view the website and blog (marketing also writes the right things). That is what you should do before starting to write.
Check, edit and check again. The technical writers themselves must do the initial check. After that one more. And only after all these checks we can involve support, marketing, and other departments in reviewing the article. Another technical writer ar the editor (if you have one) should do the final reading.
Spread the article after publication. Once the article is written, there is definitely someone who needs it. Spread it: translate, place a link in the interface, give it to marketing, and support.

50 questions to ask

While working on the documentation, we repeated the same mistakes. Besides, it took too much time. The problem was in our approach and the content itself. So we decided to put all the questions that we were constantly asking each other in one list categorized in 7 steps. Use it if you are also writing documentation.

Goals and audience

  1. Who am I writing an article for? Who is the future reader: user, administrator, or developer?
  2. What jobs have to be done? Is there a description customer person?
  3. What is this user’s level of training? What does he/she already know? What is not obvious to him/her?
  4. How can I 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/she 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. Should this article be accompanied by a video instruction?

Sources of information

  1. Do current users have issues related to the topic of the article?
  2. How does support explain what has to be done?
  3. Did the marketing department write articles and news on this topic in our blog?
  4. Are there any sections on our website dedicated to this topic?
  5. What did the UX and product manager put into the script? Why did they do it like this?
  6. How is this question described by competitors?
  7. In which areas can you see the best practices?

Contents

  1. Did we achieve the goal of the article?
  2. Will everything be understood by a more advanced user?
  3. Will everything be clear to the novice user?
  4. Is everything logical and consistent?
  5. Is the sequence of actions correct? Will the user be able to achieve the goal, following only this instruction?
  6. Did we take into account all use cases?
  7. Does the article fit into the section in which it is located?

Layouts

  1. Are there any unreadable sheets of text?
  2. Are there long paragraphs?
  3. Are paragraphs too short?
  4. Are the lists too long?
  5. Are there any over-complex lists (those with more than two or three levels)?
  6. Are there enough images?
  7. Are there not too many images? Do we illustrate too obvious steps?
  8. If there are schemes, are they clear?
  9. Are tables difficult for perception?
  10. Does the page look good in general?

Copyediting

  1. Is everything in compliance with our style guide?
  2. Does the style match the rest of the documentation?
  3. Are there sentences that can be simplified?
  4. Are there complex terms that require explanation?
  5. Are the style not too official?
  6. Does it have replays?
  7. Does anything hurt your ears?

Final proofreading

  1. Are there any typos, spelling errors, and punctuation mistakes?
  2. Are all translations, paragraphs, and sections in order?
  3. Are all images signed?
  4. Are the interface elements named correctly?
  5. Are there links provided? Do they work and lead where they should be?

After publication

  1. Does the article have sections that are required in other articles?
  2. Should this article be referred to from others? If so, which ones?
  3. Do we need to add a quick link to this article in the product interface?
  4. Do we need to send a link to support, marketing, or other departments?
  5. Do we need to submit an article for translation?
  6. Do we need to submit an article for translation?
This list can be printed and put on the desktop or hang on the wall. You can also turn it 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 so that features would not be released without user documentation.

Irina Varnina

Marketing manager