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 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

  • Think that the reader has no context. Imagine yourself to be reading the page with no context who has come seeking knowledge. Give a small intro to what the document will be about.
  • Bold, italics, strikethrough, underline, headings, are at your disposal to use as you see fit. Just don’t overuse them, else the document will seem overwhelming.
  • The distinction between ordered lists and unordered lists is that ordered lists give a relative importance to the content it has, lower number being implying more importance. Most of the times, unordered lists work.

    • Use sub-lists to group related points
  • Use large blocks of text under a collapsible if the underlying information is either extraneous or adds value for those who are curious and want to know more
  • Tag people if you want their input on the topic. Comments work better for this. Tag people in task documentation often. Document your tasks with progress and findings.
  • Put dates where you think it might add value by knowing the chronology. Generally useful in postmortem or Root Cause Analysis (RCA).
  • Avoid using abbreviated forms too much, it just looks lazy. As for acronyms, if it is a technical term then use the acronym only after you have made it clear what it means at the beginning of the document.
  • Tables are generally used where a specific format with 3 or more columns. If there is only a key:value, it is better to use bullet points. Use tables for statistical information.
  • Write it such that you will want to come back and refer to it again. This is underrated. Write it if you will come back after 6 months and the document still provides the intended knowledge.
  • If your documentation tool allows you to add tags, please use it. In time you will figure out how well the search functionality works and how it finds keywords etc. Use it to make your document findable!

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 someone gotta do it, let it be you.