Documentation: Just Do It.

March 03, 2022

About three years into my tenure with a previous company, I took the helm developing a large web application. It began with relatively simple requirements, but quickly bloomed into a multi-faceted system running a plethora of cross-platform automation and integrations.

The company had the vibe of a start-up, but was decades in business. This wasn’t a development house or a software company. We moved fast and rolled out projects to drive business, with little time to tackle technical debt.

At the time I took on the aforementioned project, I was a budding web developer with the knack for solving business problems with code – but I lacked a proper mentor and software engineering leadership. During development, I did my best to document with comments in code, and to structure things nicely… but in retrospect, I had gaps in knowledge of best practices.

Fast-forward a few years: the system was successfully launched and had been running well for a while. New features were occasionally added, and additional integrations were developed to serve new business needs. I was growing as a developer and learning all I could from books, engaging with the community online, and listening to podcasts.

🔑 This is key: Keep learning no matter what. Software development moves fast and failure to stay sharp can result in a stagnant career.

I came to realization that our growing technical footprint became too much for one person to maintain. Much of the underlying web of code, databases and integrations was organized in my mind. Our software was growing, but our development team wasn’t. There was no redundancy of technical knowledge. This is a dangerous position for an organization to be in.

I remember thinking long and hard about how to sell upper management on our need for documentation. In hindsight it seems ridiculous that it had to be pitched as important to begin with. I formulated what I thought to be a reasonable plan: I’d take one day per week to craft documentation tracing back through all our connected systems. I expected the process to take perhaps 6-12 months to fully document everything at this pace, and then I’d factor in time to document anything new along the way.

This request was denied.

I continued another year or so, building/updating/improving systems without the addition of documentation. Doing what I was asked.

At one point, I had to revisit an older system and patch an update because of an API change. As I dived into the old codebase, I was lost and confused, unsure how the system even worked anymore… I couldn’t even remember how to find the staging environment. I spent the better part of an entire day demystifying this thing that I myself built years prior. This was the day I realized I had no choice but to document.

The solution: I set up an internal website using GatsbyJS and markdown files to be able to quickly jot down my notes as I coded. These notes would eventually be refined into more elaborate documents, which grew into a system of documentation to serve for onboarding (and as reminders to myself). Any time I tackled any project, I added or improved its documentation.

As I’ve grown in this field I’ve learned that writing good documentation is part of the developer’s job. Documentation is not a task to “fit it in if there’s time”it’s a must-have.

TL;DR: Don’t ask for permission to document your work. Just do it.


Leave a comment. Let's discuss!

MichaelWritten by Michael - His career path has allowed him to incorporate his creative eye with a love of programming, analytical thinking, and learning. Michael has been married to his lovely wife Yohana since 2012. They have four wonderful children, two St. Bernard dogs, and a chinchilla. Follow @missionmikedev on Twitter