Documentation: Yes, We Should!
Imagine you recently joined a new team, and after a couple of weeks, you were assigned a bug ticket. You look at the ticket and decide to see if this issue surfaced in the past and so do a search in the bug tracking tool.
Success! A single search hit.
You get excited. This will be a quick fix. You’re just going to apply the solution in the ticket returned in the search result. Blinded by hubris, you open the ticket, and this is what you find:
Rather than finding anything useful that would guide you on your path to fixing your bug ticket, you find a single-word comment. Fixed. This single word now leads to so many questions in your mind:
- What was the cause?
- Was it a frontend or backend issue?
- Why does it only affect specific users?
- Was it a code or a configuration-related issue?
- How was it fixed?
With a dejected feeling, you realize that, now, you would have to investigate this issue yourself.
Future Us / Future You
There is a very high likelihood that the code you have written today will be maintained by other engineers/developers in the future. They are the “Future Us.” And if you stay in the same company for a few years, “Future You” will end up maintaining the same code.
You spend a few hours identifying the cause, applying the fix, and, crucially, documenting the issue and the fix you rediscover. This pattern repeats as you work on more tickets.
Documentation — Why Should We?
One can give a wide variety of reasons why we should write documentation, but here are three reasons that are worth considering:
- Onboarding
- Efficiency
- Product Overview
Onboarding
As a consultant at Tarka Labs, most of the projects we get to work on are brownfield. Over the years, working on different brownfield projects for clients, a common thread we have observed is that, at the start, significant time is spent onboarding a new team member. Most of the time lost is due to the following:
- Challenges setting up local development environment due to out-of-date or incomplete README or setup instructions
- Lack of clear understanding of the different workflows in the application
- No documents highlighting the interactions/integrations with other third-party services
Clear documentation can assist a new developer in quickly getting oriented with the application and significantly reducing the onboarding period.
Efficiency
The DRY (Don’t repeat yourself) principle in software development encourages us to avoid duplicating code/effort. Similarly, if we have good documentation of our application or investigation findings, it assists us in keeping things DRY and saves time for Future Us/You. Additionally, documenting the investigation findings can be a source of valuable information for the developer working on fixing the bug.
Product Overview
One can understand the features quickly without needing additional assistance for simple CRUD (create, read, update, delete) applications. However, there is more going on for more extensive, complex applications than the basic CRUD actions. Some aspects of a complex application are:
- Code is written in a specific paradigm.
- Depending on the requirements, various design patterns are used.
- Calls various third-party APIs
- Implements custom algorithm for specific business needs
It is possible to figure out everything that is going on while relying solely on source code, but it can be daunting. Therefore, documentation is an essential PART of coding and not something one does outside of coding.
Arguments Against Documentation
Code is the source of truth.
While there is no arguing that code is the source of truth, having documentation that gives an overview of how things work can save significant time for new team members in learning the application.
Documentation quickly gets out of date.
This is a consequence of documentation being an afterthought rather than a part of the software development process. As professional software developers/engineers, we should give the same love to keeping our documentation up to date as we do to keep our code clean.
No time for writing documentation
Similar to the previous point, we should consider documentation as part of our development process rather than something we do on the side.
Writing documentation is boring.
Fair point. However, it can become an incentive if we remind ourselves that we are doing this for Future Us. Also, just as in life, we wouldn’t always get to work on the fun and exciting stuff; sometimes, we have to do the boring stuff.
In conclusion, as professionals, it should be our responsibility to treat documentation as part of the coding process and write accurate, useful documentation for Future Us and Future You.
