I recently presented a talk called “Back to the Feature” at the South African Scrum User Group (SUGSA) conference. The talk playfully references aspects of the Back to the Future trilogy to illustrate how business analysis can be done effectively in an agile environment. This article focusses on one specific topic I covered during the presentation – that written documentation is one of the worst ways to communicate with other humans*.
* And no, the irony of writing a detailed blog post about how poor written documentation is at communicating information is not lost on me!
The first Back to the Future movie concludes with Doc telling Marty, “Roads? Where we’re going, we don’t need roads!” I paraphrase this iconic movie quote as, “Written documentation? With what we’re building, we don’t need (much) written documentation!”
Overwhelmed with Information
My agenda slot was on day two at the conference so I could relax on day one. I was pleased to see that IQ Business, one of the conference’s Gold Sponsors, had a gourmet coffee station as part of their vendor stand. Over the course of the conference, I consumed a substantial amount of IQ coffee but my first cappuccino was the most memorable. Having just placed my order, I overheard an interesting interaction behind me. A fellow caffeine deprived conference attendee asked one of the IQ team, “Do you have almond milk?”
“I’m not sure, let me check.” was the reply. I did not want the barista to get distracted and produce a suboptimal brew and therefore pointed to the large sign directly in front of us clearly stating, “Almond milk is available on request”. Now it could be a UX design issue (as you can see from the picture below a white font on a light blue background does not provide the best contrast) but we are bombarded with a huge amount of information these days and there is only so much we can take in. I thought this provided a nice simple example of why a conversation is superior to the written word and worked it into my conference talk.
To further illustrate the point, I blacked out the four types of coffee listed on the sign and asked my audience if they knew what the four items were. By this stage of the conference almost everyone in the room would have tried one of IQ’s coffees and stood face to face with this sign. There was a lot of guess work in the room and it took some time before all four of the actual documented products were covered*.
* I am not sure why the two most popular options, “Cappuccino” and “Latte”, were not listed but these are my drinks of choice and I can confirm that, despite what the written documentation said, they were definitely available.
Behavioural science experiments have shown that we react to and remember pictures and physical objects much better than words. One of my favourites also involves coffee. In this study, patrons of a coffee shop were given a coupon that could only be used on a Thursday. A reminder notice was pinned to a board in the coffee shop but, in addition, some of the customers were told that there’d be a green alien on the cash register to remind them to use the coupon on Thursday. As you would expect, customers who were told about the green alien had a much higher coupon cash-in rate.
At functions, one of the most effective ways of advertising what drinks are on offer is to display the options on top of the bar so that one does not have to ask, “What beer do you have?” The question becomes redundant as you can see the selection which saves processing time and increases throughput. There’s nothing worse than being thirsty and having to wait in a long queue at the bar – flow time for beer is very important. In the case of our coffee station, maybe they should have embellished the sign with a large picture of an almond (or have a jar of almonds on display).
Short Memories & Shorter Attention Spans
During one of the less exciting talks on day one, I was scrolling through the conference program and thought I’d take the opportunity to read my own talk abstract again. The last time I looked at it was several months previously when I did a final proofread before clicking the “Submit proposal” button.
I had done a slightly different version of the same talk at the South African Business Analysis Summit in 2022 but used the SUGSA conference as an opportunity to make some upgrades and improvements to the content. To my consternation, I realised that I missed one of my own requirements having promised to show “how an innovation day can change the paradigm and move you to documentation-less development” in the abstract but had forgotten to include this enhancement to my slide deck.
My first thought was, “It’s OK, no one will notice if I leave it out.” but the more devious part of my brain conjured up a cunning plan to work this blunder into my talk…
At the ‘end’ of my presentation I put up the “Any questions?” credits slide and then said, “Wait a minute, there’s one final hidden scene for you.” I then asked the audience, “Who read the abstract before coming to the talk?” About half the room raised their hand. I followed this up with, “There was one item in the abstract that I have completely omitted, does anyone know what it is?” I was not surprised that no one even volunteered a guess.
This provided the opportunity to cover the story about a team who used an innovation day to solve the problem of physical versus online story boards (and did so with documentation-less analysis and development).
Solving the Story Board Dilemma
When it comes to the physical versus online story board dilemma, I like having both (and generally recommend this for teams) although there is an overhead with the duplication.
Online boards automatically track all your metrics as you do the work and are a necessity for dispersed teams. However, there is something about the tactile nature of a physical board that cannot be reproduced virtually. Plus a physical board is always visible for collated team members (unlike an online board which only gets sporadic viewings) and you can change your physical board’s look, feel and structure in seconds but simple improvements can prove expensive or even impossible when you are constrained by a tool.
What this team did was buy a cheap webcam and add QR codes to their story cards. In less than a day, they developed a solution that would detect when a card was moved on the physical board and this automatically triggered a status update in the source system (in their case RallyDev). In a few hours they solved a real world problem with a great solution. In doing so, they did plenty of analysis but not one piece of written documentation was produced to build the solution (they did subsequentially create some written documentation for maintenance and support purposes). This is a great example of individuals and interactions improving the processes and tools!
Had they gone the traditional route (even with an agile approach), it would have taken months (and many documents) to get business case approvals, budget, prioritisation and produce written requirements before a single line of code was written – let alone a solution produced. Principle number one in the Agile Manifesto is, “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.” Efficient, appropriate analysis should speed up the delivery of working software but in most cases requiring unnecessary written documentation slows down the flow of value.
Written Documentation Without Conversation is Always Ambiguous
My final example in this article is not something I covered at the conference but is a clever ice-breaker that I like to use when I facilitate online training with Product Owners and Product Managers.
I put a simple, one sentence instruction into the chat: “When is Mother’s Day in five years’ time?”
I tell the class that they cannot ask me any questions but they can use Google or whatever source they like to get the answer. I also tell them not to put the answer into the chat until I say so. After a couple of minutes, I get everyone to hit the send button at the same time. Of course no one gets the ‘right’ answer on the first attempt,
I then allow people to ask me questions. There are various tricks up my sleeve and my ‘right’ answer is always once the last trick has been uncovered. Some of these tricks are that Mother’s Day is a different date in the UK than in South Africa or the USA, does “5 years’ time” include or exclude the current year and that I have an unspecified specified date format in mind.
One simple requirement but many incorrect answers unless we clarify expectations with a simple conversation. Written documentation without rich conversation is always suboptimal and, in many cases, proves largely useless.
How Much Written Documentation is Enough?
There are occasionally edge cases where reams of written documentation might be required*. However, if you are iteratively building small pieces of work, communicating effectively as a team and have no lag time between analysis and build, then lengthy written documentation should be the exception rather than the norm.
* I would always recommend brutally scrutinising whether written documentation is genuinely required or if there is a better solution. For example, someone might say we need to document all the error codes for our coffee machine so that if something goes wrong, the barista can look up what the problem is. I would counter this with, “What if we made the error messages so clear and intuitive that the barista knew exactly what the problem was without having to look at a manual?”
What is the smallest amount of documentation normally required? I would argue that it is short description or hypothesis covering the “why” and acceptance criteria. The acceptance criteria would then evolve into your test cases. If you have too many acceptance criteria, your story or feature is too big and you should split it. Lean 101 is that small items flow faster through a system and has the added benefit of exponentially reducing risk (half the size is about a quarter of the risk).
The Flawed Argument for Written Documentation
When I chat to people about the business case for written documentation, three main arguments are provided – all are easily refutable.
The first is, “So developers know what to code and testers know what to test.” Here it’s worth repeating a previous point – if you are iteratively building small chunks of value, communicating effectively as a team and have no lag time between analysis and build, then written documentation is largely superfluous.
The second argument is, “So that when something goes wrong, we know where the problem is and how to fix it.” Ask your production support team whether they look at written documentation when they get an incident. Invariably they don’t because documents are hard to locate, are usually out of date (it’s impossible and very time consuming to keep written documentation in sync with production) and, even when they are able to easily find an up-to-date document, it’s very difficult to locate and quickly understand the specific piece of information that they are looking for.
How can we satisfy the ‘quick diagnosis when there’s an incident’ need? Take a look at your (ideally automated) test cases. Test cases become the single source of truth for comparing how the system actually works to how it should work. Like an accounting ledger you have debits and credits. If the books don’t balance, figure out whether it’s your production system or your test cases that are faulty and get your books to balance again by fixing the problem.
The final argument is, “So that when new people join our team, they can understand how the system works.” Imagine if I tried to ‘document’ my house for you. Compare the experience of giving you a lengthy, one-dimensional written description versus sending you some photos versus a physical visit. If you were joining a new team, would you prefer to read hundreds of pages of written documentation or play around in the system? Even the most diligent bibliophile would gain a much richer understanding by playing around inside the system – and for an in-depth understanding of specific functionality and business rules, the test cases are once again the best option.
The Voice is Mightier than the Pen
There is a lot more I could cover but, since this is an article about how terrible written documentation is at conveying information, I think it’s best I stop now. If you made it this far in the article and learnt something – congratulations on being an anomaly! For everyone else, I’d be happy to present the conference talk again. And of course, if you disagree with any of the above – let’s chat!
As for me I’m off to chat to my wife about what to cook for dinner – this is another case where I’ve found that a friendly conversation produces much better results (and a more appetising meal) than sending her written requirements.
Follow Running Mann:
