Why you can’t afford to let lazy documentation practices jeopardise your project
I’m not prone to exaggeration. I’ll admit, I’m a born pragmatist and a pedant for details (the glass isn’t half-empty but it is only operating at 50% of capacity).
So hear me when I tell you: this article might well be the most valuable you ever read.
Your software documentation (from scheduling and estimates to your design, architecture, and source code) is the very foundation of learning for all the stakeholders involved, as well as a solid platform for the basis of your product. It’s the How, When and Why of your project and ensures absolute clarity of purpose and process right from the outset.
And yet it’s an aspect of the development process so easily and so often neglected. It’s the fine print you skim over. The ugly sister to the idea, the big plans and dollar signs in your eye’s. It’s just human nature.
A lot of development teams gloss over the importance of thorough documentation too, which is, at best, negligent. In my eyes, damn near criminal! They don’t understand the fundamentals, they don’t have the manpower or the discipline. They don’t want to scare you off with the cost.
Same principle with the raft of low-cost, off-shore providers you may have come across. Happy to cut corners. Lacking the resources, experience and discipline to hold up the process. They just want your name on that contract, why should they worry about your ability to scale later on down the road? If you make it that far…
When your documentation and note-taking is not thorough and systematic you are building your house on quick-sand. Not to be a party-pooper or a plot-spoiler but EVERY. SINGLE. PROJECT. will suffer some problems.
And when they come – and they will – if your attempts to fix them are hampered by disorderly or incomplete documentation, spread out over multiple portals, various versions clogging your communication channels, then it’s not just a huge ball-ache (pardon my salty language) but it can be absolutely critical. Or, should I say, terminal.
- Missed or misunderstood requirements, leading to….
- Stretched deadlines and delays, resulting in…
- Hidden costs and ballooning budget, risking…
- Missed scope of work, even potential…
- Legal issues.
And if you actually make it through that shit-storm? (apologies again for the language, I don’t know what’s got into me today…)
- You are unable to transfer your knowledge (what if you need to refactor the code? It’s like trying to crawl back into Shawshank blindfolded) and thus unable to scale. In fact, you might be in a position where the only option is to…
- Start all over again!
Now this is not scare-mongering, this is hard-won experience. This is what I have seen – looking into the eyes of people who have come to me after being seduced by a kiss and promise from lazy, cheap or downright unscrupulous technology partners who didn’t make them confront the awkward questions at the start.
- NO discussion on business or user needs
- NO explanation as to why chosen technologies are a good fit
- NO factoring in of maintenance projects
- NO discussion of alternative ways to build the project
- NO risk assessment at base level
And
- NO real consideration to scalability after (why would they?)
There are two ways to learn that lesson and I only hope you are able to get yours here. For free.
It’s disgusting how some providers will lead new entrepreneurs down a merry road just to make a quick buck themselves. It’s morally repugnant and borderline fraud. Yet they get away with it time and time again.
Of course, there is a degree of culpability with the entrepreneur too. Documentation of product and process is the due diligence of software development. If you don’t check the numbers add up, if you don’t check under the hood, then many would say sympathy should be in short supply.
The smallest violin in the world playing just for you.
Thorough and comprehensive documentation takes effort and manpower. It needs to be systematic and rigorous. This takes time and it costs money. But it’s a false economy to try to skimp on it. In the end, you will get what you paid for, (just maybe not what you were promised).
