Let’s Bring Back Documentation In Software Development
In the early days of my career, I was mocked by my teammates for being a documentation guy. My task involved creating a bunch of documents depicting user stories, and nothing else, for weeks.
The task was purely verbose. It bored me so much, that I almost left my software career. I pleaded to my boss to assign me some real coding stuff.
To my surprise, he put me into an elevated task:
Write functional and technical specs.
Being a beginner, I hesitantly concurred, but later on, I began to understand the fullest extent of its potential.
I appreciated it from the bottom of my heart, for it played a very crucial part in formation of a programmer: myself. The only part that was left to accomplish was coding by hand / copy-paste from reliable source.
That final part, as I realized, was only 20% of a programmer’s daily routine. I had already surmounted 80% during documenting.
Why Is It Fashionable & Trendy To Hate Documentation:
Every time there is discussion about software development life cycle, developers and project managers are divided into two camps: Waterfall vs Agile.
Since Agile has somehow positioned itself as ultimate cost-saver by validating frequently and delivering early, documentation has taken a backseat due to it being primary ingredient of waterfall model.
Besides, it appears to be adding no tangible value to the end user.
Efficient coders publicly hate documentation. They discuss the design in team meetings. They will fill up a whiteboard in 3 minutes. But they won’t document.
But their reasons for hating documentation are sometimes creepy.
More often than not, rockstar developers are fearful of putting their take on a design decision in a document. A document that can some day come back and haunt them.
They publicly advocate and demand on jumping on the real thing, instead of wasting ePaper.
And junior developers simply idolize them.
The fact is: every super-efficient coder professing great hands-on has considerable documentation under his / her belt. It could be scratch pad notes in trash cans, or whiteboards rubbed a million times.
He / She is simply reluctant to admit it publicly.
What Makes Documentation The Crucial 20% In Development Pareto?
Pareto states:
20% of the invested input is responsible for 80% of the results obtained
If you had to sharpen your axe in software development, documentation is your tool to sharpen that axe.
20% time invested after documentation can be transformed to effective and smooth development during 80% of the SDLC time.
This is because documentation gifts you with the most crucial asset: Time to think over the solution. I expanded on that idea over here:
It’s the same thing that you do while taking a shower, in transit, or making your morning coffee.
Documentation can take the cognitive output of those tasks one level further, and solidifies the mental sketch of features to develop.
The key thing is not to repeat the mistake I did in the beginning of my career. Do not busy yourself in endless docx creation. Instead, keep coding intermittently. Keep coming back to your descriptions, specifications and flow charts.
You are already doing it every day on scratch pads and whiteboards, in the form of block diagrams, flowcharts, and notes.
Documentation simply ensures:
- You do it in a sophisticated way
- You make it sharable with colleagues — both present and future ones
- You create a snapshot of your team’s development activity at specific time. Future teams can go back to that snapshot any time, and make revolutionary revivals possible, just like renaissance did of Greek and Roman art.
Conclusion:
Documentation has powered ISO certified product companies that runs today’s world including Boeing, Lockheed Martin and NASA.
Documentation is underrated in today’s Agile world. However, all tools surrounding Agile have great offerings on documenting. Let’s bring back the documentation before robots start writing better programs and overpower us.