Have you ever taken something for granted and only realized its value when it's gone? Here's what'd happen if Apple, Walmart and our banking system lost access to software documentation.
Innerworks is coming soon...
This blog was originally published on our previous Cogworks blog page. The Cogworks Blog is in the process of evolving into Innerworks, our new community-driven tech blog. With Innerworks, we aim to provide a space for collaboration, knowledge-sharing, and connection within the wider tech community. Watch this space for Innerworks updates, but don't worry - you'll still be able to access content from the original Cogworks Blog if you want.
Imagine software documentation disappears.
Poof.
Into thin air, it goes.
Developers rejoice as they can now take a break from the detailed documentation process and do what matters; code!
Digital leaders get a sinking feeling as the only written guidance to create the next digital version vanishes!
There may be mixed reactions to the loss of software documentation. Do we need it?
To understand, let's imagine a world without it:
A world without Software Documentation.
Software documentation is the ultimate guide to understanding software aimed at everyone who could come into contact with the software: developers, designers, QAs, end users, stakeholders, marketers, agencies, and so on.
What would the world be without software documentation?
- Update roulette would be the new normal.
The most obvious software documentation example can be found in your phone settings -> software update.
The team at Apple, for example, releases notes every few weeks, including information about what the update will achieve. These release notes we see on our phones are what's known as "end-user" focused software documentation.
Source: Forbes, iOS 16.0.3—What To Know About Apple's New iPhone Upgrade.
Apple are notorious for sparking debate on whether users should or should not upgrade their devices,
Luckily, global media company Forbes, and others like it, are on-hand with articles like 'Apple iOS 16.3 Release: Should You Upgrade? to try out the upgrade for you, mitigating risks for millions of users that rely on iOS.
Without release notes (software documentation), news outlets would have much less to discuss. Plus, users would have less freedom to make an informed choice on whether or not to upgrade, leading them into an unwanted game of "upgrade roulette".
With every release update, there's an internal version, too, aimed at designers and developers so they can make the best decisions.
So, without good software documentation, could the iPhone cease to exist?
Maybe.
At the very least, it'd plummet in popularity.
Even the most experienced developers will eventually need guidance on how their company's systems work to find the speediest way to continue doing what Apple does best; innovate quickly!
The Fortunate 500 wouldn't be so fortunate.
In 2022, despite rising inflation, an ongoing supply chain crisis and the second year of Covid, Walmart did pretty well, winning the Forbes 500 top spot with a revenue of around $572 billion.
So why is Walmart doing so well? You guessed it. Software. According to the Walmart Inc - Digital Transformation Strategies, Walmart is exploring various emerging and third-party technologies, like AI, drones and augmented reality. Walmart's Text to Shop feature allows customers to connect their Walmart account with their phone number to top up groceries and deliver them to their door quickly.
Source: Walmart, Text to Shop: Walmart Customers Can Now Shop as Easily as Texting
Remember, we're imagining Software Documentation is gone.
So what happens when tech breaks? TechCrunch's review of Walmart's Text to Shop technology recently pointed out that 'the chatbot said confusing things [and] user interface was at times difficult to navigate'.
Could Walmart fix this little problem and keep its place at the top without software documentation?
Unlikely.
With no documentation, there are no coding standards. Developers would be creating complex code only a select few would understand. So, when Walmart need to sharpen their tech and a programmer is ill, on holiday or working somewhere else, mayhem ensues.
Over time, without documentation, illogical code structures would start to appear with no standard to refer to for development teams. Customers get cranky, all the programmers quit due to the pressure, and some other retailer takes the hotspot.
Still with us?
It could happen.
Financial institutions would flop.
It doesn't matter if the software is open-source or closed; financial institutions, like banks and investment and insurance companies, rely on software to manage daily operations and survive in their industry. In recent years, banks have been favouring open-source technology.
Why? Software Documentation. It’s at the heart of a thriving open-source ecosystem. Banks are realising the enormous benefit of collaboration by giving to open source technology and reaping the benefits of what's already available.
There are a couple of ways banks use Software Documentation:
1. Banks create and donate their own open-source solutions to standardise elements of the banking system. These systems are heavily documented and openly available so that they can address widespread industry challenges and drive innovation. In 2020, a leading global investment bank, Goldman Sachs, donated its open-source Legend programme to help other firms in the financial industry better control their financial data!
2. Financial Services also use existing open technologies to make up their technology stack (a website or application has layers of technology that are carefully chosen, known as a tech stack). Within that tech stack might be APIs, Cloud Services, Headless architecture and Microservices-based technology. Every element of technology in a tech stack requires detailed software documentation for developers to understand how to weave it best together and create truly open composable tech.
Final thoughts?
In the age of digitalisation, almost every pillar of society would become less effective without documentation; healthcare, government, financial, technical and so on, so software documentation is as essential as the software itself.
We need Software Documentation to be better digital creatives and leaders, not to mention happier customers. Smaller start-ups can struggle to see the value of software documentation in the early days, but an organisation with more than one employee is wise to start noting down the basic processes.
The world is a better place with software documentation, and writing it certainly feels much less of a chore when we harbour a culture where software development is treated as the star of the show that it is.