Issues and Thoughts on Documentation Writing Encountered at Work

I’m not sure if “documentation writing” is a topic worthy of discussion in other industries, but in the IT industry, it’s definitely a topic that deserves in - depth discussion.

In my past work experiences, I often encountered or heard others complaining that there was no documentation for a certain system or API, making it extremely difficult or even impossible to take over the work.
Since I’ve realized this problem, I pay more attention to documentation writing in my work. I try to document all the aspects that I think others might need to know. However, I still find there are many issues. Today, I’m writing this note to record these problems and my views.

Let me directly state the problems I’ve observed as follows:

1. How can you make others aware that you’ve written documentation for a certain problem?
2. Can the readers understand the documentation you’ve written?
3. How do you maintain these documents? (Mainly the issues of updating and management)
4. Is the documentation you’ve written necessary?

To be honest, I don’t have perfect solutions to the above problems, but I do have some personal feelings and experiences. Next, I’ll discuss these problems one by one.

How can you make others aware that you’ve written documentation for a certain problem?

Generally speaking, whether it’s internal documentation or online documentation, no one will read the entire document before starting work. You can recall your own process of reading documents. Take myself as an example. I usually look at the table of contents first and then find the part I need. I will never read the document from beginning to end.

So, how should you make others aware that you’ve written documentation for this problem?

Take my recent experience as an example.
In the past few months, I’ve been in charge of the company’s artifact management system. To promote and help users (other R & D colleagues in the company) get familiar with this system, I’ve written a lot of documentation, from basic configuration to permission management, and then to best practices. However, I still often encounter others coming to ask questions that have already been documented.
We made some optimizations, which seemed to be somewhat effective. The optimization items are as follows:

1. Create an index for the documentation
   Create a new blank document and put all the links to other documents in this one. Write a one - line description for each link so that readers can know what problem is recorded in that link. And this description should be as concise as possible under the premise of accuracy.
   The advantage of doing this is that readers don’t need to jump between different pages to find the documentation for a problem, reducing the “searching” (not viewing) obstacles of the documentation.
2. Create a customer service system
   Our company has a dialogue system that can return the links to corresponding documents according to keywords based on user input. I’ve tagged the documents with some keywords so that when users ask questions, this system can return the corresponding documents. However, this dialogue system is a bit “dumb”, and the effect is not very good (but it’s still useful). So currently, this part of the work mainly relies on the help of another colleague. He will give the corresponding links according to users’ questions. But ChatGPT makes me believe that this method will be more effective in the future. If ChatGPT launches an enterprise version, we can train it based on our own documents and FAQs, and then let ChatGPT answer users’ questions.
3. Promote newly created and highly - visited documents irregularly
   We will send our newly created documents and those with high visit volumes to users (in groups and via email) irregularly. But we must control the frequency. If it’s too frequent, users will feel annoyed, which will have the opposite effect.

Can the readers understand the documentation you’ve written?

When writing documentation (including blogs), one of the most common mistakes is not writing from the readers’ perspective.

We often write based on our own knowledge and experience, but this often leads to readers not understanding the documents we write.
The simplest way to verify this is to ask 2 - 3 other colleagues to review the document and see if they can understand it.

There is a method in the writing process that can solve this problem to a certain extent. That is, when writing each document, consider readers with zero experience. Put the prerequisite knowledge points and documents needed in the current document in the form of links so that readers can check them when needed. In fact, many excellent open - source software documents are written in this way.

How do you maintain these documents?

As time goes by, we write more and more documents, and some may become outdated. So, how should we manage them?

Sometimes, messy and outdated documents can be harmful to work. For example, if the function of system parameters changes and is not updated in a timely manner, if a user uses a destructive parameter, the consequences could be disastrous.

I’ll write about maintenance in two parts: management and update.

Management

Our company has always used Atlassian’s wiki to write documents. Generally speaking, this is quite good. Documents can be arranged according to the organizational structure and product catalog. It is said that Feishu can also achieve similar functions.

Recently, a colleague in the team discovered a new way to manage documents. I think it’s great and plan to give it a try.
Put the documents in the form of Markdown files in the company’s own GitHub repository, and then synchronize them to the wiki through a plugin. The obvious advantage of doing this is that there is a version management function, because Atlassian’s wiki itself doesn’t have this. In addition, writing documents in Markdown is more friendly to programmers.

Update

Another huge challenge in maintaining documents is updating, especially for the software documents released within the company.
Because for commercial software, the documents must be updated. This is driven by both the pressure from commercial customers (the so - called “clients”) and the market’s profit - making (making money￥￥) drive. So, it’s usually not too difficult to keep commercial software updated.
However, for software released within the company, due to the lack of the above two driving factors, it’s a bit difficult to keep the documents updated.

But there are still two feasible ways to “try our best” to keep the documents updated.

1. Select those who pursue perfection in the team to be in charge of internal software
   Such people, often because of their pursuit of perfection, will take the initiative to update the documents.
2. Establish a document review mechanism
   At least for those very important systems, a document review mechanism should be established.
   This has two advantages. One is that it can keep the documents updated as they should be. The other is that it can make other team members familiar with these documents, because they need to participate in the review. In this way, to a certain extent, team members can back each other up.

Is the documentation you’ve written necessary?

When I first took charge of the artifact management system, I spent a lot of time writing documentation, hoping to cover everything. But later, I found that some of the documents were unnecessary.

So, how do you know if the documentation you’ve written is necessary?

There are two methods, which are used before and after writing the documentation respectively.
After writing the documentation, you can pay attention to its reading volume. If no one reads it or the reading volume is very low, it means that this document is probably unnecessary. (Or the document is very poorly written)

Before writing the documentation, you can collect users’ questions first and then start writing, avoiding writing according to your own preferences.