Why you should write documentation

Have you ever been in a situation when a colleague asks you a question you've been answering many times? Or, you want to understand why someone decided to go with the X framework and not Y?

In a team

Often, even the person who coded the feature doesn't remember why it's done this exact way. Then who to ask about the information? The image below describes the areas of features responsibility between CTO and Michael. What happens when CTO and/or Michael quit?

It can't be only one or a few people to be responsible for a feature. It's usually true. CEO devised the initial idea. His co-founder amended it. In a general meeting, the first PO adjusted the requirements, the second PO added a few new points to discuss. Weeks later, they gather a technical meeting. It turned out, if they will be delivering emails from its servers, it'd slow down the overall response time. Tech guys recommend rejecting 3 things from the idea. And so on.

The implementation differs from the initial idea, of course. Now, what happens if I want to know about the idea more? I should ask the CEO, his co-founder, one designer, 2 POs, and a tech team, which was implementing it. Is it difficult to ask though?

While you can ask many people about it, it may be hard to collect enough data because:

• it's easy to forget;
• there may be no people who were responsible for the implementation/review;
• it's time-consuming;

Do you think it's time-consuming to ask? You jump on a call with people and they tell you how it was devised and done. Approximately. Do you find it difficult? Okay, it seems not.

Then let's forget about this idea of documenting things for a moment. And get hired for another company where all people remember what they've done. Also, where people don't quit.

On your 3rd day at the company, you get a first task to do! A bug when creating user profiles. You take a look at the code and understand it's hard to grasp where things are happening. John, your colleague, can help with it because he wrote the registration module.

John explained the code well to you. Now, you're feeling the impostor syndrome, and go fixing the bug. After hours later, you realize the problem may lay in the payment handling module. Yura, a manager, recommends you ask a girl out from the other team - she may help.

You eventually fixed the bug. After months passed, you realize that for almost every task you do in this complex system, you should ask for help from at least one person. Some tasks require asking a few.

You start noticing the gradual changes in your calendar.

The work became more about explaining something and asking questions. Can we tackle that? Okay, let's find another job and start things from scratch. Things like writing documentation.

Now, we understand how it's important to document decisions, how do things work, etc. The job should become easier.

The drawback of docs is the necessity to update them. We wrote the docs. Isn't that enough?

Information may become obsolete. Writing it is one deal, but you also should review the papers and figure out what should be adjusted. Some things don't require adjustments in the future. For example, describing why a decision was made. It's salient to understand why we/you/they did something in X way.

If you describe a general overview of a project, it's okay to have a description of the common features and not technical details. There is a problem with tech details: they change over time. The product's primary idea isn't, usually. Even if it's, it's not difficult to rewrite a few sentences. From a technical perspective, there are many things to cover - databases, APIs, what services are responsible for X, how to debug Y, etc. All these things change, and it's important to write down why did we make a change.

Documentation best practices

These are my best practices, they may not suit you or your company's requirements/views. If you have suggestions on how to do better - please tell me.

A simple rule to apply for all kinds of docs is to write important stuff. How to determine importance?

• you think someone will ask about it in the future;
• you think you'll ask this info later;

It's important? Write it down somewhere. The next problem is that we can have documentation, but a few people know where to find it. For example, you may store technical docs in git repositories as a README, product docs in Confluence, marketing team docs in Notion, hiring docs in an internal hiring CRM tool.

Problem? One can describe the same process in different places. Or, we may forget to remove the obsolete docs from one source. When one wants to find actual docs, she may spend additional time to figure out what are the relevant docs. So, keep the docs in one place.

The same principles apply to software documentation. And some explicit hints. Write about:

• how to run a project locally;
• API, possible payloads, and errors;
• motivation and a goal of this project;
• code style guides;
• how to contribute;
• prerequisites to launch;
• how to deploy;
• dependencies;
• anything else that someone will search for;

When estimating tasks, take into account the time needed to write or update docs. If you read a paper and understand something is missing, add it.

Write down the important stuff because you and others will forget it. Pick one place to store the docs. Review them periodically and update if necessary.

Follow me on Twitter