Mandatory steps in properly planning and developing successful software applications.
To please and keep both customers and all project stakeholders aligned, and be able to transfer or scale your digital product with ease, you MUST have good documentation – and yes; that’s both process documentation and product documentation.
Good record-keeping and documentation of all project aspects are some of the keys to building, maintaining and scaling a quality digital product.
To understand why that’s the case, let’s begin with contemplating quality.
Thereafter we’ll push on to examine just how a companies process around software documentation builds the case for choosing a software provider who is able to grant your wish of ‘quality’.
What Is ‘Quality’ Software Documentation?
Ah, that old chestnut – ‘Quality’, “The standard of something as measured against other things of a similar kind; the degree of excellence of something.” – Oxford Living Dictionary.
Why am I leading with a definition?
Because, as you are aware, quality is subjective. Therefore it is not easily defined.
When it comes to software development, the hallmarks of ‘quality’ are excellent planning, implementation and transparent communication throughout the software development life cycle (SDLC), expressed in performant technology that is coded with the future of your product in mind.
The finished article works as expected.
All stakeholders and users can understand it at the level required.
Developers can pick it up and run with it because it is easy to transfer, maintain and scale.
At least, that’s what most people think….
However,
” In software development, the basis of the level of quality is what you specify; it’s not about the word quality – that’s subjective.”
— Creative Stack’s Project Manager T.C
Just to clarify the terminology:
What is the difference between requirement and specification in software engineering?
The key difference between requirement and specification in Software Engineering is that a requirement is a need of a stakeholder that the software should address, while a specification is a technical document with the analysed requirements. A specification describes the features and behaviour of the software.
This is a neat way of saying that the requirements/specifications for your project determine if the outcome will be a quality piece of software.
One that is ready to be loved by all users – your Minimum Loveable Product (MLP)!
Why am I telling you that?
Simply because I want you to succeed!
Are you determined? Need to make sure your digital product makes an impact?
Then check out the path to market to make sure you walk with certainty towards success.
Software Product Path to Market: Prototype → MVP → MMP → MLP.
The terms are explained, and it’s laid out as neatly as possible for a short read.
What Are The Types Of Software Documentation?
Many of our clients are confused by the umbrella term ‘documentation’, and it’s easy to see why – in the software industry the term refers to several different types of documents for specific purposes.
Here’s a dirty breakdown of the types of software documentation:
And, this is just an overview to illustrate my point – it’s easy to get confused, and this confusion is compounded by the fact that many software companies do not properly explain why each subset of process documentation and product documentation is essential.
Right, but why would a company choose not to explain something that, to a large extent, determines if your project will be of ‘quality’?
” If you can’t describe what you are doing as a process, you don’t know what you’re doing.
— W. Edwards Deming.
A lot of dev teams gloss over the importance of a thorough documentation process because it is difficult to explain, which implies they do not understand the fundamentals, and/or they do not have the discipline and/or manpower to produce sufficiently detailed documents.
Worse still, the process and product documentation have voids where important information should reside, or it’s not up-to-date.
Either way, your digital product is undermined by a lack of comprehensive documentation.
As a consequence, transferring knowledge becomes difficult.
As mentioned in my other article, these factors are hallmarks of an unreliable provider and are common with low-cost, offshore providers who cut corners, or lack the resource, experience and discipline to hold up the process.
So, beware → do your due diligence, that is if it’s quality you’re after?
Here’s the low-down from an expert to make sure you pick the right provider.
Back to the point:
The whole point of documentation is to enable learning: an easy transfer of knowledge from one stakeholder to another in order to understand the ‘what; ‘how’ and ‘why’ in your project.
In effect, this means there is clarity in the entire process. Plus scaling or maintaining your digital product is a breeze as it is accessible.
In truth:
” Most people try to create good documentation, and it’s not [weak] because they don’t try or take it seriously – usually it’s because they aren’t doing it in the right way. “
— David Laing | The Grand Unified Theory of Documentation.
Let’s unpick why documentation and good practices around record-keeping are the foundations that support your digital product.
Why Software Documentation Is Important
Simply, you can’t expect a good quality product without due process: aka documentation.
A good record of complete and well-written documents are not only required but are fundamental to ensure that quality software products are delivered.
These documents must be inclusive of all project stakeholders – from both the Client’s and Contracting Partner’s sides.
Just like practising ‘loving kindness’ is the opposite of ‘selfishness’, good process documentation and product documentation practices are the antithesis of negligence in software development.
Don’t kid yourself expecting a “cheap and quality solution” from a provider who can offer nothing more than a low-cost offer.
BUT, regardless of the cost base, the hallmarks of a quality provider are evident in their process for developing a digital product – their documentation practises are at the forefront of their development efforts.
After all, it’s the foundation of understanding and learning for all stakeholders involved, as well as a solid platform for the future of your product. Thus, thought, care and consideration are necessary.
Let me run you through another analogy:
In reference to some philosophy I picked up over the years; ‘yes’ means nothing without a ‘why’, or a ‘how’…
What do I mean by that? It’s easy to say ‘yes’ when you’re promised a golden solution, agree to a price and walk away without being certain of what will happen.
The ‘How’ ‘When’ and ‘Why’ of the documentation process is often forgotten.
Just as long as you get the end product at the price you want – it doesn’t matter right? WRONG.
- That’s a common mistake – you need clarity around any software company’s processes, especially if you are looking for quality implementation. As a part of due diligence, ask for examples of their process and product documentation – it will be very apparent if they can deliver.
Of course, you do need to know what you’re looking for… but more on that another time.
I’d suggest asking for examples of documentation from any software company – to see if it’s up to scratch.
OK, fine – what’s next?
To ensure that you will receive updated, comprehensive documents that support your digital product development throughout the software development life cycle (SDLC), you need that ‘How’, ‘When’ & ‘Why’!
Here’s what your auricles and tympanic membranes need – some resonance along the lines of:
‘Yes’, and here’s ‘how’. This is ‘when’ it’s going to happen and ‘why’ these set documents are essential for x set purpose, and ‘why’ they support your digital product.
Through quality process documentation and product documentation, all parties are able to be certain that what is delivered is also what was specified at any given stage.
Why? Because, at its core, a good standard of documentation allows all parties to feel confident:
It’s a failsafe record that shows the process of developing a digital product.
The steps to build the intricacies of the product, how it works – It’s all there.
Consequently, at the end of the SDLC, the documentation also improves the transfer and maintenance of your product.
Ready to scale your project? Not without proper documentation, no – you are not!
If it’s incomplete – you’re looking at reverse-engineering the system to fill in those gaps.
Ultimately, documentation underpins a quality software development process, reduces risk, and increases the chance of quality delivery.
Simply put:
“Better documentation will make your project more successful”
“It 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 its problem.
— David Laing | The Grand Unified Theory of Documentation.
Essentially, if a user can’t use it and a software developer can’t pick it up and run with it – you are cutting the flight feathers of a fledgling bird before it can take off.
Just like you can’t have loyalty without trust – one vanishes without the other – you can’t have a quality digital product without documentation.
As Frank put’s it;
“You can’t have one without the other”
— Frank Sinatra | Love And Marriage.
Thanks for sticking with and pressing on!
It’s time to delve into the details of how good documentation = quality software project delivery.
How Does Software Documentation Ensure Good Project Delivery & Higher Levels Of Quality?
Imagine that you’re trying to be accountable for what has been said and done, and yet – you are lost on the paper trail. It’s disorderly too – all the documents are spread out via multiple portals and various versions are clogging communication channels. It’s just a mess for everyone involved.
Procedural ‘filing’ errors and lack of commitment and discipline to orderly communication are big ‘no-nos’ in software development.
Good, up-to-date documentation stamps across all mistakes and makes them easy to trace.
Plus, it’s legitimately better to have the right documents up-to-date and in the right place.
Common sense, no?
Such a comprehensive paper trail keeps internal and external stakeholders aligned, and it gives them confidence in the project objectives, as well as providing clarity as to what’s happening at each step in the process of development.
Therefore, at any given point it’s easy to raise questions and discuss.
In light of that, any risk is reduced – there is predictable progress, and quality is factored within the budget.
Consequentially, damage control (god forbid) is a simple process and any project can be brought back on track with a simple meeting: everyone is accountable because of their commitment to; yes, good record keeping & process and product documentation practices.
Should anything untoward occur, documentation also underpins litigation: avoidance of, or successful action. There’s no need for finger-pointing or bickering – it’s crystal clear who is responsible. Easily settled.
To summarise and drive the point across once more, looking to the future of your digital product by investing in the documentation process early on saves headaches and back-tracking with a hazy memory of exactly what has happened and why.
If not, there will be gaps; and those gaps are the difference between success and failure – finishing on time and budget versus spiralling costs.
Thus, producing and updating the documentation as you go bridges all the gaps, and so increases the chances that your product will be a hit.
Check out these examples for some more clarity:
What Happens When Software Documentation Is An Afterthought?
Do you know why vague specifications for quality software products never work?
If you don’t, are you willing to risk:
- Missed Scope Of Works?
- Misunderstood Requirements?
- Delays?
- Exceeding Budget?
- Legal Issues?
Clearly not, and that’s why documentation is essential.
You cannot have a quality digital product without comprehensive, well-written documentation – please forgive me for sounding like a broken record.
In fact, the more complex and intricate the development work and the loftier your vision for your product – the more effort, precision, and discipline are required in the software documentation process.
I digress….
It’s well-known that people have different levels of expertise and understanding.
For this reason, you can’t rely on simple briefs or patchy gaps in confusing documents.
If you do, you are leaving yourself open to misinterpretation and misunderstanding – you’re asking for it.
Then there’s the fact that documents immediately lose their value if they are not up-to-date…
To illustrate my point, let’s take this example:
# 1 A product owner (client) vaguely says: “I need X product with ‘Z’ feature fast and for a low cost. This Minimal Viable Product (MVP) needs to validate my innovative idea – and quickly.”
They supply a simple brief…
That’s it? Yup.
Here, the product owner does not produce a sufficient product requirement brief.
The focus is on the delivery time and price, not asking about the methods required to make sure they get what they ask for – or if what they are asking for will solve their problem – it’s an afterthought.
The product owner sees that the provider makes software products so the ‘how to’ part is assumed.
That is; they do not ask about their processes. Too much is assumed.
# 2 The software house costs the project as they understand that ‘X’ product with ‘Y & Z’ features, and gives an estimate with a promise of quality – it’s low, and can be done fast.
The Software provider sees it as simple. But, business requirements have not been discussed thoroughly – ‘the why’ in this project is opaque.
The roadmap and technologies are chosen fit the base requirements.
But nothing else – performance, maintainability, extending the product – or at worst its purpose – are not considered. It’s likely they’ll build with the software they know without offering alternatives.
Red Flags:
- No discussion on business or user needs.
- No explanation as to why chosen technologies are a good fit.
- No maintenance projections are factored in.
- Scalability is an afterthought.
- No discussion about other ways of building the product.
- No risk assessment at base level.
A point worth reiterating:
Comprehensive documentation is an essential art form, and it is difficult to get it right without due process and considerable thought – It requires effort and discipline, and that skilled manpower comes at a price.
# 3 The product owner is delighted and quickly agrees to the low-cost offer.
He’s reassured that his ideals are possible – fast, two-feature MVP.
Simple, right?
However, the product owner lacks the experience and technical skill to manage the provider; he can’t understand all the tech terms around the implementation and has a basic understanding of the technology stack.
He didn’t want to seem foolish either, so he didn’t question the process at all.
And, we know that this is a false promise – you can’t have low-cost and quality in a short timeframe.
Without diligence around documentation practices, among other things, you are doing business without sincerity.
Neither party effectively communicates thereafter bar a few:
‘Where are we with this?’
‘Here’s an update’
‘Is it on track’ etc…
The product owner is only concerned about getting his product in hand. Just some basic use-cases about the product and what it should do – In that sense, they are aligned at the top-level view… but that’s about it.
# 4 The software is produced.
Some documentation is written along the way, a few gaps are filled at the last minute – the product is finished, it sort of ‘works’, but it lacks proper documentation.
Your dish is served cold.
# 5 The product owner says ‘that’s not how I wanted ‘X’ with ‘Z’ feature.
Why is this not the quality I was promised?
⇒ Bickering & fingerpointing ensues.
Both parties are at fault here, so neither can agree.
No one can really remember what was said or why certain decisions were made.
There is a lack of accountability due to that.
Plus, there are gaps between ‘Brief’ and ‘End Product’ where there should be comprehensive process and product documents.
This patchy record means that neither party knows what happened and why.
#6 The solution: more resources are needed; maybe a different supplier?
The timeline is stretched and the budget is shot.
“But… I said ‘Y & Z ‘ freatures with ‘X’ functions for my MVP… the brief was clear?!”
” I need it with more features and to take on more users”
” I can’t understand how the product works”
This list goes on…
I would continue, but you get the picture:
Information was sparsely communicated and the product was poorly documented.
All too common.
You’ve probably experienced this sort of situation before? But If you haven’t, you can expect:
- Miscommunication.
- Lax attention to detail.
- Language barriers.
- Lackadaisical project management.
- Hidden costs.
- Missed requirements.
- Stretched timelines.
- Lack of foresight for scalability & maintenance.
- Promises that can’t be kept.
Now imagine that, as this is often the case, several ‘low-cost’ providers outsource their work to even lower-cost companies…!
At an even lower cost-base, you can expect slovenly coding and a communication breakdown – surely no one has the full picture?
Outcomes: Spend more to get less; now you have to reverse engineer your project and refactor the code and add in those missed requirements…All without the proper documents that clearly shows the process used to build your product.
Is this code a incomprehensible cipher..?!
Is it me.. Or is this a bad dream?
We could all do without those painful nights fretting over the ROI and regretting a choice of provider.
All you want is to get your project back on track.
Even though this company seemed like a different path up the same mountain, your digital product is undermined.
I digress…
Did you factor in the intangible costs of taking that path?
If you didn’t, you’re not alone.
As a consequence, your health, focus and mindset suffer…
That’s it – you’ve had enough!
Your innovative idea has crashed and you’re burnt out.
The lesson: Do your due diligence.
- Be mindful of choosing a low-cost provider without a good process and track record.
- Beware of providers who over-promise.
- Spend more time evaluating ‘what’ you need and ‘why’.
If you end up on that route, expect that you will get what you paid for – but not what you were promised, or had in mind i.e. you’ll find yourself ploughing more resources into fixing the product, transferring it is a hassle, and then you’ll struggle to maintain it.
Scaling it becomes an insurmountable task.
Pissing in the wind comes to mind.
Let’s flip that around for a second…
Is Software Documentation Good?
Think of it this way: if you properly plan, scope, and thoroughly document your project you are laying the foundations for it to succeed. The documentation process is time-consuming and costly, but there is no alternative if you are seeking quality – this comes at a cost.
That said, a thorough set of requirements documents means that your project should cost less in the long term: akin to building a house; once the blueprints and plans are finalised, and foundations are laid, you do not necessarily need the best builders around to ensure you have a quality home.
Granted, it could fall apart with unskilled workers…but if your lead foreman/project manager is skilled and highly experienced, it will still be a reliable structure that becomes a habitable home.
On that note, a good indicator of hitting the mark here is knowing you have that skilled project manager and architect on board – make sure you know they are in for the long haul too!
In a similar vein, comprehensive documentation allows for development work to be sourced to mid-level, or even junior, software engineers.
Of course, this does depend on the complexity of your project.
We always advise a battled-tested architect and project manager to oversee the works, but you get the idea here – you get what you pay for, and just because poor processes and a lack of documentation = likely unsatisfactory outcome, doesn’t mean that reams of paper and constant check-in’s = magnificent outcome.
As with anything, mid-market rates prove palatable and you CAN produce very high-quality software.
However, you need to keep your wits about you when searching for a provider and know how to identify a good one when you meet them.
Then – you are ahead of the game.
Here’s How:
Make sure you follow the right path and tread with assurance by finding the right strategic partner.
Here are some hints and tips:
Back to the point:
” Just like building a house, when you break a complex project down to blueprints, schematics, the architecture, design, materials, construction methods and an action plan, it can be understood by the various types of labourers from different backgrounds.”
” When you have that step-by-step plan, software development is as simple as putting the different building blocks together. Everything runs smoothly with a good plan.”
” The problems arise when there are missing specifications leading to guesswork, poor documentation, and culminating in unrealistic solution design that won’t meet the project requirements.”
— Creative Stack Advisor J.F.
Why Software Documentation Is Important
Taken together, a thorough and comprehensive documentation process allows everyone involved to be sure of what is taking place at any point, that progress is being made, and why decisions and certain implementation has occurred.
Everyone is held accountable for their decisions and for the quality of the end product – which is actually good quality.
It must be stressed just how essential it is to keep a systematic practice for concise note-taking, record keeping, and updating documents on both the client’s and provider’s sides, to ensure that all stakeholders are on the same page.
In sum, this avoids disagreements and delivery issues and provides a proven method for maintaining a professional and effective working partnership.
Find out how to build an effective technology partnership with this free guide:
Creative Stack receives many projects with sparse documentation from new clients who are concerned about their current technology provider.
They come to us when software houses have over-promised, cut corners, misled them with low-ball offers, resulting in accrual of extra, inexplainable fees [read: avoidable fees] too!
These poor souls have sadly been led down the rabbit hole, sold on a kiss and a promise; made to believe that quality products can be built in a short space of time for a low cost.
You simply cannot produce something of quality without the right management, development process, or resources to back it up.
It takes time, and for good reason.
The process a company uses must always incorporate accurate, up-to-date, relevant documentation to support the entire software development project – from the requirements brief right through the software development life cycle (SDLC).
In this way, it’s easy to transfer, maintain and scale the product.
AND, please remember:
” It 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 its problem.”
— The Grand Unified Theory of Documentation. David Laing.
If a user can’t use it and a software developer can’t pick it up and run with it – your digital product is still just an idea.
Improve your chances of turning your innovative idea into a loveable product on the path to market:
Prototype → MVP → MMP → MLP.
It’s a short read that runs through the steps, funding, terminology and some hints and tips to help you succeed.
Greg Whitfield,
MD Creative Stack.
