Technical documentation is a debate that has unleashed passions in different teams, whatever their specialties for decades. When it needs to be written, it is deprioritized and when it is missing from a project, it delays all teams. I will therefore look at the problems of the technical documentation that I was able to observe while working as a technical writer and developer.
A Thousand and One Reasons Not to Do Documentation
I'm not going to lie, doing documentation is not the most fun part of our jobs, but it is an integral part of it. I even think that to be a good “tech”, you don’t just have to know how to “puke code”, you have to know how to document and understand product needs, among other things. However, in many cases it is omitted, or avoided for multiple reasons. I don't think there's any good reason to avoid documentation, so I'll go through some excuses I hear quite often and see why it doesn't make sense.
If the Code Is Clear, There Is No Need for Documentation.
Surely one of the most common excuse, in reality it reflects a deeper problem. The goal of technical documentation is not to explain the lines of code but the context of the implementation and to give an overall view to save time and efficiency.
You know how to develop, the person who will take over the code knows it too. However, what they don't know is the context in which this was done and why. Because we all know, sometimes we make strange choices that are necessary because of the context. For example, why redevelop a function to do an action, why implement a program this way. There may be reasons, technical or political, but these reasons will not be seen in the code at first glance. However, you should also not be overzealous and over-comment, having more comment lines than code is often symbolic of a problem. Let's take a telling example that I still see often, comment lines like this:
# Allows you to retrieve the ID
function get_id():
return this.id
The comment does nothing except increase the number of lines.
We will reduce the number of man-days on documentation.
Another phrase that you must have heard often! Because yes, many IT projects end up being delayed, as in many other areas. To reduce delays, project managers have a fairly classic technique: eliminate or reduce the time given to non-priority tasks. Retain by “non-priority” all tasks that do not directly bring a return. Suffice to say that this often contains: optimization, refactoring, and documentation. So yes, it saves a few man days immediately, but in the long term this approach is not profitable. The application will have a life cycle which will need to be modified and updated many times. Every time someone has to work on it, they are going to have to take time to understand the code and the context before they can work. It is rare that over the entire life cycle of the product this is profitable.
Added to this is yet another point: you must not reinvent the wheel, so reuse the code as often as possible. If you want your code to be reused, one of the first criteria will be the presence of documentation and its organization. Example: if you do Infra As Code with Terraform, it will take you more time to separate the elements into independent modules, but you or others will be able to reuse them for various projects.
We Have Everything Automated, There Will Be No Need for Documentation
Today with agility and the DevOps approach it is more and more common to have very mature projects on automation such as the use of continuous deployment, automated cloud infrastructure, and so on. With all this, we are sometimes tempted to say that there is no need to do documentation.
Small anecdote, I already heard an administrator who was asked by the security team to update OpenSSL urgently. He did not understand where OpenSSL was located or how to update it because in reality, he only got back a Docker image on DockerHub. I think this shows why it's important to be aware of the invisible part of the iceberg.
Knowing what automation does is part of the documentation. Six months after going live, there is little chance of remembering the specifics of the system. The documentation will get you back on track easily, especially on infrastructures which are increasingly complex.
If I Document My Work, I Could Be Fired
This may come as a shock to some, but I have heard this phrase several times before. Moreover, it is often the same people who want to limit automation for this reason. In short, I am not throwing stones at them, I can understand that people are afraid of losing their jobs. However, we should not be fooled. From experience, the fact that there is no documentation will never prevent a company from carrying out layoffs. I even think that it will often further deteriorate the quality and the working atmosphere.
In short, don't do that, I don't think it will one day work in your favor, quite the contrary.
Documentation in the Age of Agility and DevOps
We have seen different reasons that are often given for not doing documentation but we have not addressed a particularity that is close to my heart: documentation in the age of agility and DevOps. When we accelerated the deployment of applications and infrastructures, we saved a lot of time, but what about documentation? However, reconciling the two is important and I don’t think it’s that complicated.
To manage this in the age of DevOps, I would tend to advise the following things:
The documentation must be part of the lifecycle, therefore be versioned and tagged like this. In general, I choose to store it in the git repository of the associated code, this avoids losing it in the process.
Modifications must be accompanied by associated documentation, if it is done continuously it is faster. Each merge request must be accompanied by associated documentation modifications and additions.
Writing documentation should be a reflex and should be done at the same time as the code as if it were an integral part of it. I do not recommend putting just one documentation task at the end of the project; distribute it among the technical tasks; it is an integral part of it.
Automate as much as possible, when you document Terraform modules or REST APIs there are tools to automate a lot of it like versions, input/output, etc.
Bring it to life, often people tend to stop reading and directly ask about cats . We have all received messages on Slack or elsewhere asking questions to which the answers were in the documentation. Kindly refer these people to the documentation and ask them to contact you again if it is not precise enough, if this is the case, improve it! Because tomorrow you may be on vacation and you won't be able to answer.
Everyone must document what they do, it is not up to one person to take responsibility for such a central and important point.
These are the few points that seem important to me to have an effective documentation methodology in a DevOps environment. The list nevertheless remains personal and not exhaustive.
Finally: RTFM
Documentation is important, it saves time for you and future technicians. Yes, with reverse engineering, you can get away with it, I happened to come across obscure programs that I had to understand strace, ncor else tcpdump, but it is time-consuming and not effective in the long term. Also, don't be afraid to respond “Read The Fucking Manual” to someone, in order to give them the reflex to read the documentation so that they gain autonomy.
As a freelance techincal writer, usually my goal is not to stay ad vitam aeternam with the client, but to help them take control so that before I leave, I only have to give them the manual and the keys to his new system.
If you don't do it for yourself, do it for the person who comes after you. Maybe you can save him weeks of uninteresting and time-consuming work.
Top comments (1)
This is an amazing piece. The importance of a technical documentation can never be over- emphasized.
However, many people today do not like to read docs. Some prefer to watch videos, etc but I personally agree with you that documentation should be the answer to so many questions we have about projects and technologies.
Thank you for sharing.