Aiming for "It's All Written There"

Introduction

Are you all writing documentation?
I write it sometimes, and sometimes I don't.
However, I recently felt that leaving documentation is important, so this post is a reflection of my thoughts on that.
Note that the documentation I'm referring to here is not about project overviews or values related to user benefits, but rather internal designs and implementation procedures written for developers.

The Key Point of This Article!!!

I will work hard on leaving documentation.

"Ask Me Anything" is a Trap

This is the biggest reason why I wanted to start leaving documentation.
I don't think "Ask me anything" is ever used in its literal sense.
Specifically, I recognize that "Ask me anything" implicitly means "Ask me anything about what you couldn't find after searching."
Therefore, the actual process of asking a question follows this flow:
① Encounter an unclear point
② Research on the internet or in books
③ Still don't understand
④ Ask a question while describing what was researched
This flow of asking seems natural.
However, the path from ① to ③ might actually be unnecessary.
If the solution is already known or if it's a project-specific matter, asking is faster than researching.
By asking, you don't need to waste time and can perform tasks efficiently.
On the other hand, if you worry alone without asking and spend time on something that could be solved immediately, you delay the progress that was originally expected.
Because of this, people who can ask a question if they haven't figured it out after 30 minutes, or those who can do so, are often said to be "good at asking questions."
Asking questions properly like this is important.
Therefore, we should learn the appropriate timing for questions and aim for operational efficiency.
However, I also think it's not good to leave this timing for questions solely to individual effort.
As the person receiving questions, I believe it's equally important to establish criteria for whether a topic is worth worrying about.
Without criteria, individuals are left to choose whether a question is something they should ask or something they should research themselves.
On the other hand, let's look at a case where the following rules are ingrained:
① A question arises.
② Search the project documentation.
③ If you can't find the information you need, ask a question OR report that it's not in the documentation and state you will investigate.
④ Find a solution
⑤ Record it
If the culture of doing things this way is a shared understanding within the team, the chances of worrying over known issues will decrease.
Whether the rules in the example are appropriate or whether the documentation is in an easily searchable state are details that should be discussed, but at least the systemic problem of being able to worry over known issues can be reduced.
I want to create such a situation, and I believe the foundation for that is the enrichment of documentation.

What Kind of Content Should be Recorded?

I believe even the following is acceptable as content to write:

If you want to do XX to YY, ask Mr./Ms. ~.

While it might only tell you that you won't know without asking someone, it shows that the topic has been raised in the project and a path to the solution has been presented. I believe the value of putting this into words is that it makes this path visible.

The value in this case lies in lowering the hurdle to asking questions.
First, because the person to ask is clearly identified, less time is spent searching for someone who knows the answer.
Furthermore, when asking, you no longer need to explain every single detail; you can simply provide a link to the recorded content and say, "I want to do what is written here," allowing both parties to reach an agreement on the goal. This also reduces the time the questioner spends debating whether to figure it out themselves or ask someone.
This alone makes documentation worth keeping.

However, since this only serves as a contact list as it is, it is preferable for the questioner or respondent to add further details as they go, but I believe any content is fine to record. The important thing is to create a shared understanding that "the information should be there." Rather than giving up on writing altogether because you feel you must write it perfectly, I hope you will at least leave a record for now with the intention of completing the content gradually.

What to Record?

I mentioned that any content is fine and that recording itself is what's important, but we should consider what kind of events should be documented in the first place.
In my opinion, the following two types of things should be recorded:

• Project-specific implementation procedures
• Cases where you cannot find the information you need on Qiita, Zenn, or personal blogs

Let's look at each of these.

Thing to Record #1: Project-Specific Implementation Procedures

I believe everything specific to the project should be recorded.
Here, "specific" includes not only coding conventions but also implementation procedures that you want to unify.
Let me give an example of an implementation procedure to unify.
Suppose you are building a BFF and a backend with NestJS and implementing communication between them.
In this case, the technology being used and the implementation procedure should be documented.
For instance, if you are communicating via gRPC but haven't documented it, a newcomer might try to communicate via REST.
This would cause significant rework.
While a scenario like the above is unlikely to happen, simply recording the fact that you use gRPC is insufficient.
Looking at the documentation, the client side for gRPC communication in NestJS uses ClientsModule.
However, it is possible to communicate without using ClientsModule.
Therefore, if some sort of procedure is not established, communication will be carried out through various means, leading to a state where values can be retrieved for only certain functions for reasons that are not well understood.
To avoid the above case, it is a natural progression to decide that the project will use ClientsModule for communication.
This agreement is precisely the implementation procedure to be unified.
In summary, even when there are multiple methods available, if the project has decided on a specific one, that decision should also be documented.

Thing to Record #2: Cases where you cannot find the information you need on Qiita, Zenn, or personal blogs

In this case, I'm referring to situations where information on the matter is not widely handled, and access to the information is difficult.
Therefore, it will take more time for others to resolve the same problem if they encounter it again.
However, since the problem has already been solved before, searching for it again is a waste of time.
While re-digesting reference information can lead to better understanding, spending time just to find a solution that has already been found is unlikely to bring significant value.
I believe technical matters like these, which aren't necessarily project-specific but have little available information and are hard to access, should also be left as text.
On the other hand, I think recording something like how to use the JavaScript map function—which you can find plenty of results for by searching—is honestly a waste of time.
I use the amount of information available in Japanese as a criterion for that line.

When You Don't Need to Leave Documentation

It cannot be said that strictly leaving documentation is correct for every project.
First, consider a case where you are implementing something alone and there is almost no chance of more people being added in the future.
In this case, as long as the person themselves understands it, there aren't many readers compared to the effort of writing thorough documentation.
Basically, documentation within a project is only read by people who want to know specific information.
Therefore, when the reader is the same as the writer, the raison d'être of the documentation isn't really there.
And if there isn't much opportunity for more developers to be added, it wouldn't take much time to explain it each time they join.
The significance of leaving documentation is to prevent an increase in the time required to deliver value.
In other words, if leaving documentation does not lead to an increase in the time available to deliver value, it may even have a negative impact.

To Increase Each Other's Time for Delivering Value

I have been reflecting on keeping records up to this point.
Because of this, some might feel that I want to eliminate synchronous communication and make it so that work can revolve solely around asynchronous communication.
In fact, I've written this so far with the intention of making people think that way.
However, I do not want to eliminate synchronous communication.
Rather, I am aiming to enrich asynchronous communication in order to enhance the value of synchronous communication.
I believe it's important to solve problems asynchronously if they can be solved that way, thereby freeing up time for synchronous communication.
There are many things that can only be achieved through synchronous communication, such as understanding team members and discussing how to deliver value.
On the other hand, there aren't many problems that can only be solved asynchronously.
While we use text-based communication for the purpose of leaving evidence, from the perspective of value creation, I can't think of many things that can only be solved asynchronously.
In this way, synchronous communication is a bundle of possibilities and is extremely valuable.
It's a huge waste to spend time on things that could be solved via asynchronous communication during that valuable synchronous communication time.
In order to secure more time for synchronous communication that generates value, I wanted to enrich the foundation of asynchronous communication, and I wrote this article as a declaration of intent.
(Postscript: After I finished writing the draft of this article, I came across Mr. Sakurai's video titled "Boosting Internal Pressure to the Max [Work Attitude]". I thought it was very educational, and at the same time, I felt like this article might actually release that pressure. But since I went through the effort of writing it, I decided to post it anyway.)

Conclusion

In this article, I wrote about my thoughts on documentation and my commitment to working hard on it in the future.
After reading books like "GitLab ni Manabu Sekai Saisentan no Remote Soshiki no Tsukurikata" (Learning from GitLab: How to Build the World's Most Advanced Remote Organization) and "Hito ga Fuetemo Hayaku Naranai ~Henka o Hoyo seyo~" (Adding More People Doesn't Make It Faster: Embrace Change), I thought they contained great points and decided to write this in connection with documentation, which is one of my interests.

However, this article is incomplete.
First, it's because I haven't been able to express much of the content from the two books mentioned above or many of the things I wanted to write.
In particular, I was very impressed and convinced by Section 1 of Chapter 2, "Even with double the budget, you won't get double the productivity," in "Hito ga Fuetemo Hayaku Naranai ~Henka o Hoyo seyo~." I really wanted to incorporate its content, but I couldn't do it well.
It’s frustrating that I can't convey the appeal of the above due to my lack of writing skills, so please do read "Hito ga Fuetemo Hayaku Naranai ~Henka o Hoyo seyo~."

The second reason it's incomplete is that it's still at the stage of a declaration of intent.
While I intend to leave records here and there, I haven't yet put into practice how those records actually turned out to be useful.
Therefore, there is a high possibility that I will be forced to make corrections once I actually try it.
Whether this article ends up being just a desk theory depends on what happens next, so I still consider it unfinished.

As my writing skills improve and documentation matures, I hope to look back on how my thoughts have evolved.
Thank you for reading this far.