Hi, I am Sunny, a technical writer at WhaTap Labs. Today I would like to talk about why you need good technical documentation.

And I will talk about what we do at WhaTap to create good documentation.

3 reasons why you need good technical documentation

First, your documentation shows the quality of your organization.

Some people may think that no matter how well you write your technical documentation, your clients will not see it anyway. You might feel like it cannot possibly be any different. But it is different. There is a difference between a well-written document and a poorly written document. Sometimes a company's official documents contain typos, spelling, and spacing errors. When a customer sees these official documents, they might think: "This company cannot even follow basic grammar, and I wonder if they are going to do a good job. Good companies pay attention to the details, and that is how they maintain their credibility.

Second, well-written documentation saves you and your clients time.

It is frustrating for clients too - sometimes it is much quicker to find the relevant documentation than to wait for an answer. But what if you cannot find a solution no matter how much you look? It is frustrating to read something and not know what it means, and even more frustrating to contact customer support and not get an answer right away. The customer experience will be negatively impacted.

Finally, documentation is a corporate asset.

Sure, it is important to develop a good product. But equally important is documenting the proper usage and process for the product you have developed. You might be thinking, "Why do I need to document this when I can just ask the developer directly? I am too busy and it is too much trouble.

But if you have to ask your developer every time you need something, you will end up spending more money. What if the developer leaves the company? What if the developer has a personal emergency and cannot get back to you right away? The bigger your company gets, the more you need to keep records. Relying on just one person to do it for you can make things even bigger when there is an emergency.

How we reorganized our documentation

1. Reorganized the documentation structure

Previously, when you clicked Documentation on the main page, the submenus were Support Home, Documentation, Release Notes, and Customer Support. To see the guide documentation, you had to click on the documentation menu and then click on documentation again, which was cumbersome.

In our current reorganized documentation structure, the documentation page opens in a new window when you hit the documentation menu on the main page. Release notes are embedded within the documentation page. The old, underutilized, consolidated format of the support pages (FAQs) has been included as a detailed table of contents within each relevant category. For example, troubleshooting instructions for installing the Java Agent can be found in the related menu, Install.

No matter which agent you are installing, there are common steps you will need to take. For example, signing up, creating a project, and issuing a license. Instead of putting these required steps in each language-specific agent documentation, we have separated them into a category called Getting Started.

2. Usability testing and immediate reflection in documentation

When developers create a new feature, technical writers prepare the guide documentation in time for deployment: the DevOps team writes the explanation of the underlying concepts (although this can vary), the front-end writes the how-to for the UI, and so on.

At this point, the technical writers test the new features themselves. As they try it out, they carefully check for any inconsistencies with the guide documentation. For example, sometimes we change the names of menus on the screen during development but do not reflect them in the documentation. We go through the process of refining the documentation by checking for these details. I also check for typos and spelling mistakes.

In addition, I think about what I would want to know if I were a user and add it to the guide. In the first draft of the guide, I did not explain why it was necessary, who could set it, and how to modify it if you forgot it. I checked with the developers to make sure it was correct, and then I added it to the guide.

3. Constantly gather internal feedback

Good documentation is a team effort. It is hard for a technical writer to do it all alone. I get feedback from the DevOps team I am a part of, as well as other relevant team members, and immediately incorporate it into the documentation. Once reflected, I share the updated parts of the technical documentation with the people who deal directly with clients.

4. Add links to related documentation

Previously, Service release notes only listed what new features were added. Now, we link to descriptions of related features in the release notes. For example, in the Service 1.50.0 release note posted on 2021-10-06, we added the Consolidated Reports feature. If you click on the word consolidated reports in the release note content, you will be taken to a guide article with a related explanation. This way, users can see what is new in the release notes and then follow the links to learn more.

Beyond this, we are also thinking about UX so that users can easily find the documentation they are looking for. Good technical documentation is not only about the content, but also about the layout and design. At WhaTap, technical writers, engineers, front-end developers, and designers in the DevOps team are all working hard to create good technical documentation.

If you have any suggestions about our documentation, we would love to hear them 😉 You can send us an email to docs@whatap.io or talk to us through our online support.

We will do our best to make it easier for you to use WhaTap products with good technical documentation.