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.

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.

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.

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.

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.