Just as any sound investment is reinforced by your due diligence, any successful software product launch is underpinned by due process- namely, proper software documentation.
A thorough documentation process allows everyone involved to be clear on WHAT is taking place at any given time, HOW that progress is being made and WHY.
It’s the platform you build on, the roadmap for the journey and the instruction manual you refer back to along the way.
” I*t doesn’t matter how good your project is, if the documentation isn’t good enough- the world’s going to say ‘thanks very much, I’ll use something else’. If the documentation isn’t good enough or doesn’t exist, the world will find another way to solve it’s problem “
— David Laing, ‘The Grand Unification Theory of Documentation’*
But what is ‘software documentation’ exactly? Here I’ll break down its separate components and you’ll see quite clearly for yourself how a gap or short-coming anywhere along the line can spell danger for the hopes of you and your product.
Software Documentation
Software documentation- as you can see from the diagram above- is the umbrella term covering all the written documents and materials used in a products life-cycle: from conception to creation and beyond.
Software documentation is broken down into two main categories: process documentation and product documentation.
1) Process Documentation
Process documentation outlines all the steps your project will take: the roadmap for ‘what’ ‘when’, ‘who’ and ‘how’.
It includes everything: from the schedule you make at the start, to the estimates and alterations you make along the way, and even the minutes you take in the meetings.
2) Product Documentation
Product documentation describes the product being developed. Instructions designed to communicate the relevant information about the product to the people who need it, when they need it: system documentation for the engineers as they develop the product and user documentation for the end-users and administrators after.
A) System Documentation
These are the documents that describe the system and it’s parts. The requirement document; design decisions; architecture descriptions; the source code; the validations, verifications and testing; and the help guide.
B) User Documentation
And lastly, the documentation needed to support the product when it’s made it to market. This is broken-down into two further sub-sections: the end-user and the system administrators.
- The end-user: this explains to the end-user how the product solves their problem and includes help guides to talk them through it’s usage.
- System administrators: these cover the functionality of the product, its behaviours and instructions on how to deal with any issues.
As you can see, this documentation of the process and the product itself is vital every step of the way, from that light-bulb moment in your head to the lovable product in the consumers’ hands.
It props up the whole project, reducing risk and increasing the chances of quality delivery.
Yet it’s an area many developers are guilty of skimping on – taking shortcuts to save time when all they are doing is kicking the can further down the road.
And I can see why they do. Let’s be honest, it’s a bit of a chore; the unglamorous stuff before the real magic happens. But to save that time cutting costs or cutting corners is a false economy.
Pay now or pay later, but the cost only goes one way.
No product finds it’s way to market without a few bumps in the road. Inadequate or incomplete documentation will have your engineers groping backwards in the dark to fix any issues, be that in development or post-production. And without proper documentation, no one else can use your code but you. It can’t be updated or improved – if you can’t remember the reasons behind your coding choices, how can you hope to scale?
In short, proper documentation is necessary to give your project a proper chance. It’s absolutely essential in terms of your organisation, accountability and scalability. The prospects of your project depend on it.
