How you can add value even through documentation in your company

Up until a month back, I used to think - "Documentation is a waste of time", "I am not that good at writing documentation", or "I rather do some task on the kanban which actually provides value", the excuses were many. But now, I will give you a reason to document.

Why only go for big tasks?

Ask yourself this - When I joined the company, could the onboarding experience be any smoother? Was any fundamental documentation when I started my first task, missing? Was there any nuanced information that existed between people, but was not documented - also known as "Tribal Knowledge"?

If your answer to any of the questions above is Yes, then you know how it feels to not have things documented. And if your answer to any of the questions above is No, you are most probably responsible for "Tribal Knowledge" and should look for places needing documentation. The most improbable case is that your company has documentation on everything 😆.

Nevertheless, the idea is... document. Document because you don't want to spend time answering fundamental questions asked by new joiners. Document because you will forget what you had done. Document because you are responsible for those who come after you, and for those who are responsible for you. Document because you want your next company to have good documentation. Start by making the change you want your company to have.

Many say that Covid19 has made it more important than ever to document knowledge, I believe that it should be important, regardless.

What if I don't like writing a lot?

The document does not have to be huge all the time. Even a few lines of documentation, if it provides the knowledge it was intended for, is good. People prefer reading small and to-the-point documentation over a verbose document.

Let me give you an example - when I working at Barclays bank, I was tasked with coding the web server for a new microservice in my team using Golang. Since Barclays is a multinational bank, it has a high level of security - we couldn't use the public golang proxy. We had to use the one that Barclays's security team had set up. Now the URL of this proxy was easy to find thanks to the documentation by a senior engineer in the company, but it became outdated as security updates were pushed and blocked packages hosted outside Barclays's network, even from GitHub 😱, where maximum important packages are hosted. Now, how do get past that - Google wouldn't have answers to Barclays's internals now, would it? Luckily, there was an environment variable setting used by Golang to solve this problem, which had been used by another engineer around the same time. That dude, Oh Lord Praise Him! had documented the variable and its value in a 4-line document on Confluence titled with the error which would show up on the terminal. Now imagine, if this dude wasn't there, we would have to code in Java. 😩

For me, this instance of documentation markedly transformed my opinion of "documentation is trash" to "where do I document?" – because I realised that there are umpteen opportunities to document, and not enough people to document; even the simplest & shortest of documentation adds value to a company. Believe it!

And for those who like numbers, consider the following scenario:

1. Amount of time spent explaining something to people with no idea about the topic = 2 hours [this is the minimum I think]
2. Amount of time spent explaining something to people with some idea about the topic = 0.5 hours
3. Amount of time spent writing a medium-sized (200-500 words) documentation = 0.5 hours [estimation on basis of knowledge on topic]
4. Hence, time saved by sending a document and then clarifying remaining doubts = 2 hours - 0.5 hours - 0.5 hours = 1 hour
5. Multiple this value by the number of people you will need to explain the topic too. A good estimation would be the size of your team. If there are 10 people in my team, you have effectively saved 10 hours of your time. And more so for many other people who will come after you. Hence total time saved in reality is much, much more!

Ok, documentation is important, but what should I document?

To start with, document what you took time to figure out and thought "Others ought to know about this!" There is a very high chance that it is either Tribal Knowledge or something new altogether. Don't worry about duplicate documents being created. If you failed to find it the first time, then it means that either the existing document is not titled correctly or the information is at the bottom of an unrelated document. And what is the worst that could happen? You add a "Related:" reference at the bottom of your document to link to an already existing page 🤷.

Just make it easy to find, what you figured out.

Quick tips about writing a decent documentation

• Format sensibly. Don't stuff your documentation with bouts of code blocks, bold, titles, headers, and tables. People will get overwhelmed and skim through the documentation.
• The most important thing about your documentation will be the small important often-overlooked stuff and caveats. For me, this is sometimes the one "if" condition that drastically changes the outcome of the feature I am working on. This also includes the environment variable controlling the feature. Highlight it with succinct headings.
• Being direct and to the point is preferable over having large narratives. This is achieved by having bullet points rather than paragraphs.
• Often remind yourself to not go out of the reader's context just because the document ties to something other feature. It is better to link to the documentation of that project or feature.
• If your document requires prior knowledge of some other feature, which happens often as features build on top of features, have "Prerequisites" with links at the top of your document (or at the beginning of the topic).
• Some parts of the documentation may be too technical and should be addressed under a suitable heading like "Advanced" or "Technical Deep-dive". Something that indicates to the Project Manager when it is time to stop 😊.
• Having many large code blocks in your documentation describing the implementation of a function that changes frequently is the worst thing ever! Have such documentation in the code itself. At most, there should be a function definition and a high-level idea of what the function does.

If you start writing, eventually you will get the hang of it.

Idea: Doc-Cop

On a rotating basis, having an engineer be the "Doc-Cop" or "Documentation Cop" who is in charge of having the documentation up to date for tasks in progress on the Kanban board.

This means that the Doc-Cop will tell the person who is the "owner" of the task to update the documentation as the task is in progress. The responsibility of the Doc-Cop may also include maintaining the quality of the documentation. It has the following benefits:

1. Saves the problem of forgetting something if the documentation of the feature is picked up later on, or if the person has left the job, by having one person responsible to police people not having docs up-to-date
2. The team would have it imbued in them that documenting is a part of their tasks – make it a deliverable of major tasks.
3. Furthermore, having it on a rotational basis, prevents one person from being labeled as "difficult" or "fussy" and being ignored altogether eventually. No one in the team should be spared from this responsibility - neither Team Leads nor Senior Engineers and especially not the Interns (gives them confidence in a new environment to speak out)!

Lastly, write to become better

Nobody will create the perfect documentation on the first attempt. A piece of documentation will become obsolete eventually. It is your job to modify/update them so that they achieve the highest possible level of perfection. Don't be afraid to document stuff thinking "I am not that good at it", nor should you just leave it up to someone else. And if someone's gotta do it, let it be you.