Moving Towards Being Agile – Documentation

Agile Documentation

The waterfall way of working lovessss documentation. They have a BRD (Business Requirements Document) that the business should produce for them before asking the developers to start working on the project. The BRD outlines what is required from the end product in detail, so that the developers know what to produce. IT are then asked to produce a design specification , where the developers document how they intend to go about producing the software based on the requirements outlined in the BRD. This includes architectural decisions, like how to store the data, what the UI will look like, what data will be displayed and where, … any questions that need answering are formulated at this stage and answers are requested. The next few months are spent writing code to fit that specification, and once it’s all done the user is given the software to test it and ensure it’s what they expect. Bugs are highlighted and fixed, and the software is released. IT expects the BRD to be immutable, and the business takes an absolute age coming up with the completed document because they have to think months into the future.

An Agile way of working has a reputation for not bothering with documentation. This is untrue – however, the documentation is not all written at the beginning as it is in a Waterfall style (as above). To be Agile means to make your architecture decisions at the LAST RESPONSIBLE MOMENT that you can, as the “cone of uncertainty” is smallest at this point. We aren’t building houses, we don’t need to know such detailed decisions from the start, because software is much more flexible than a building. Furthermore, building a house is building another instance of the same thing that we’ve done time and time again, so we have knowledge about what is likely to happen. This isn’t the case in software – if we’ve written the software before, why are we rewriting it? You can’t copy and paste a house (however much you may wish you could), you can with code 🙂

Note: There is a very clear distinction between the LAST moment and the LAST RESPONSIBLE moment. If I’m writing this blog on the tube, approaching my stop, the LAST moment to pack my laptop away would be when the doors open for my stop, at which point I could quickly put the laptop in its case, stick it under my arm, get off the train and move towards the side to put it in my bag. This does not allow for contingency, and there’s a risk i may drop my laptop in the rush to get off the tube, which would upset me to no end. The LAST RESPONSIBLE moment to put the laptop away would probably be when my stop gets announced in between the two stations. However, I don’t need to put it away 3 stops before, because then I’m losing around 5 valuable minutes of blogging!

Documentation should also be written at the last responsible moment. Ideally, it should be written AFTER you’ve written your code, but most of us aren’t that organised, so just keep it going :). Actually, ideally your tests should be written in such a way that they serve as documentation (easy to read, full coverage, describe exactly how your code should behave), so that you don’t have to keep two separate things in sync (because this rarely works, if ever. In fact, the rate at which this documentation becomes outdated is inversely proportional to the amount of time spent writing it 🙂 ). Using tests as your documentation is a notion known as living documentation.

There is no point doing things before we need to – design, test cases and documentation being three key examples – because we may end up eventually not needing it and then it would have been a waste of time to do it in the first place! We learn about the system as we work on it, so the initial upfront design has no value because we end up realising we were trying to solve the wrong problem. “We learn more about the problem as we work on the solution”.

When working in an Agile way, you can think about implementing something in a particular way, check with the user, make the decision and start the implementation in around 7 minutes (give or take a few). You don’t even need to consider that question before that point, and similarly the user doesn’t need to specify what they want until then. This could be months after the initial requirements were handed over, and the user may have changed their mind multiple times since then but you as the developer are blissfully unaware of this. In the same vein, we will almost certainly have gained much more knowledge around the domain, the code, the problem, and will be able to make a much more informed decision about the best way to go about it than at the beginning of the project. Agile allows for “useful ambiguity”.

Agile documentation and requirements should be very simple to read and understand. Given a 20 page document, on average 16 of those pages will never be touched again, and the chances of the remaining 4 pages still being true at the end of the project tends to 0. If it is too complex and convoluted to understand, people won’t try, we won’t move forward, and it has no merit. Often what happens is that the documentation ends up being everything that the writer knows on the subject with no limit/specificity. What is documented by the business will be read entirely different to the writer’s intent, as the context is missed. Furthermore, in the traditional way of working, the QA will likely have yet another different interpretation of the intended outcome and the test cases will reflect this. In the end it’s a whole load of headache that could have been averted if everyone simply spoke to each other rather than trying to express everything in a Microsoft Word document that will never be looked at again.

Disclaimer: much of the content above is based on talks given by Phil Japikse and Allen Holub at the SDD conference in London, May 2016.

<<<< Moving Towards Being Agile – Bringing in the Chickens

>>>>Moving Towards Being Agile – Planning


2 thoughts on “Moving Towards Being Agile – Documentation

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s