nisheet sinvhal

Add value even through documentation


Up until a month back I used to think, “Documentation is a waste of time”, “I am not that good at documentation”, “I am not a fluent writer”, “I rather be doing some task on the kanban which actually provides value”, the excuses are many. 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 for my first task missing? Was there any nuanced information which was there between people, but not documented - also known asTribal 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, the you are most probably responsible for Tribal Knowledge and should look for places needing documentation. The most improbable case is that your company has a documentation on everything 😆.

Nevertheless, the idea is… document. Document because you don’t want to spend time answering fundamental questions asked by new joiners which could have been a document. 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 with making the change you want your next 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 a small and to-the-point documentation over a verbose document.

Let me give you an example, when I was in Barclays, which is a multinational bank and hence has a high level of security - we just couldn’t use the normal golang proxy. We had to use the one which Barclays’s security team had setup. Now the URL of this proxy was easy to find thanks to documentation by a senior engineer, but it became outdated as a recent security update had prevented getting packages hosted outside Barclays’s network, like github 😱, where all the packages lie. Now how do get past that? Luckily, there was an environment variable setting used by golang to solve this problem, which had been used by an engineer around the same time. Luckily, that dude, Oh Lord Praise Him! had documented that in a 4 line document on Confluence titled with the error which would show up on 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; and even simple and easy things like documentation adds value to a company. Believe it!

And for those who like numbers, consider the following:

  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 to. 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, 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 repeated documents being created. If you failed to find it the first time, it means that the existing document is either not titled correctly or has the information you are about to write about is at the bottom of an unrelated document. And what is the worst that could happen? You add a “Related:” field at the bottom to link to an already existing page 🤷. If you start writing, eventually you will get the hang of it.

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, tables. People will get overwhelmed skimming through the documentation.
  • The most important thing about your documentation will be the small important often-overlooked stuff and caveats. For me, this is some times the one “if” condition which drastically changes the outcome of the feature I am working on. This also includes the environment variable controlling the feature.
  • Being direct and to the point than having large narratives is preferable. This is achieved by having bullet points under headings 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 part 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 which 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.

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 to maintain 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
  3. Furthermore, by having it on a rotational basis, it prevents one person being labelled 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. No documentation will be up to date eventually. It is your job to modify them so that they achieve the highest possible level of perfection. Don’t be afraid to document stuff thinking “I am not that good a writer”, neither should you just leave it up to someone else. And if someone’s gotta do it, let it be you.