Agile is the modern way of delivering our products and it certainly adds real value to our customers but there are times when we simply get it wrong. I want to focus upon one aspect of being Agile, the idea of ‘Working software over comprehensive documentation’. Anyone that has trained in Agile will recognise this as part of the Manifesto, it’s behind it’s origination and guiding principles. My issue is that this is often misinterpreted and leveraged by those who like to build and never document. It’s only going to make you less Agile over time.
The manifesto doesn’t call for no documentation, that’s a myth, it’s simply about streamlining it to the point where its useful but not cumbersome and by thinking more about a high-level than a low-level, detailed approach. This is particularly true when it comes to solution design and the build processes, yet this is our weak point and often the first focus on the desire to avoid any documentation.
To paraphrase the manifesto, it states that ‘Agile does not eliminate documentation, but it streamlines it in a form that gives the developer what is needed to do the work without getting bogged down in minutiae’.
The software engineering industry is historically the keenest to abandon design documents in favour of building something. We’d never build a bridge without a design, a car without specifications, a hospital without blueprints yet we invest millions in our software products and think that we can do this with no documentation at all. I know this is true, I’m an SDLC SME and former developer who hated the idea of spending any time documenting that what, the why’s, the how’s, I was just paid to code. Or so I thought.
As I moved in my career into development management, I began to see that documentation was important but not for the reasons I first thought. Documentation absolutely serves a valuable need for today’s brand-new products, but it serves a much greater needwhen bringing into consideration future maintenance and enhancements. Without any documentation we rapidly lose sight of what our code does, how it works, it’s branches, calls, dependencies and its place in the overall IT architectural landscape.
It’s easy to sit with the user and/ or analyst to hand and build what they want when it’s a new product, we’re breaking new ground after all and have no existing product to work with. The challenge with no documentation comes when the engineer, often a new team member, is expected to take that code and weave some magic to something that already exists or when we have multiple engineers all working on the same product.
Let’s use software as our example. Nowadays we very much live in a more complex world of API calls, classes, parameter calls, and so forth. We make a call sharing some information and it gives us the answer, it’s magic but this ‘glue code’ that makes it all happoen is only part of the solution. What happens when we make a call? How does that call function behind the scenes and with others to form a workable product? Often inference gets lost in the noise, the desire for a lack of paperwork and rush to prioritise software delivery over documentation and we end up playing shotgun surgery with our code, making the same changes in multiple locations. Sound familiar?
It’s said that it takes ten times longer to work out what existing software code is doing when you have only the source code to work with than it takes to work it out when you can read at least a basic set of documentation. The net result of this is that we must invest time in the future working out how things ‘work’ or fixing things we didn’t understand, and the result is that we become less Agile over time.
If we allow, in fact insist upon at least basic documentation for our projects we’re sustaining our ability to be Agile on future sprints. If you’re working on a software project imagine a world where you have an archive of existing code, a team of both existing and new developers, a high level of complexity and little to no documentation on how the current solution works, wouldn’t you see the value in at least basic design documents that show the code, its relationships and dependencies? Or, are you happy to allow a sprint or few for the developers to work out how it works or accommodate refactoring sprints to fix those defects that will appear? If you have a sprint or two of refactoring, you’re delivering code but you’re not delivering new functionality to your customer. Are you still being Agile?
If you have a project team that doesn’t want to document what it’s doing, then it’s your call but ultimately, you’re kicking the ball down the road and eventually that complexity will jump up and bite you. Remember, Agile doesn’t state anywhere that it’s ok to deliver poor quality over a workable solution. Delivering a defective product in time is of no value to you or your customer and ultimately that debt that accrues will have to be paid back somehow. That price will have to ultimately be paid by your users and customers. Is that being sustainably Agile?