Be lean (but not lacking) in your approach to documentation
Reflecting on ‘working software over comprehensive documentation’ in practice at ASOS Tech
My first ASOS blog post touched upon the Agile Manifesto’s first value of ‘people and interactions over processes and tools’. This article reflects upon the second value of ‘working software over comprehensive documentation’.
The premise of this value is that by focusing on producing software, you are able to explore, test and get feedback on the customer value and technical solution more quickly. Alongside that, we should strive to prioritise and create just enough documentation, just-in-time.
I’ll talk about some approaches that are used to adopt and optimise this value at ASOS Tech.
Prioritise your conversations and documentation, not just your requirements
As a Business Analyst/Product Owner, I focus on prioritising requirements for the development teams I work with, as well as prioritising my conversations and work/documentation in alignment to this.
It can be tempting to get involved in conversations about something that may happen in six months (or never at all) and produce documentation to that effect. While light documentation may be helpful, anything more comprehensive will likely turn to waste when things inevitably change. Being strict on ourselves, we should even consider or challenge whether it’s valuable to have any form of conversation on distant future topics.
To help with quality assurance of Business Analysis, and also help with producing ‘just enough’ documentation ‘just-in-time’, the BAs in the Content Platform Team at ASOS put together a list of mandatory and optional ‘artefacts’ that should be produced to support product development. For example, while documentation of requirements is mandatory, User Acceptance Testing scenarios are optional. We do our best to be pragmatic about optional artefacts, weighing up the time/effort to produce vs the value it will provide (as well as the opportunity cost of not doing so). We also do our utmost to produce any documentation with a just-in-time approach to protect our time and reduce the possibility of waste.
Finally, let’s remember we can break down documentation like requirements — creating small and independent pieces of work, prioritising accordingly, developing iteratively and even delivering incrementally.
Create working software to create a product that works
Working software provides an invaluable means for us to test the value of and get feedback on a particular product or feature. The faster we can get this to happen, the faster we’ll know if a product is truly ‘done’ (for the time being) or needs iterating.
Within the Content Platform Team, for the discovery phase of a product or feature, we’re seeking more help from UX to research, prototype and validate the content authoring journey. This will help us to understand the ‘ideal’ more quickly, before even starting to code.
In terms of feedback on a developed feature, the team spends time with the Content Editors to get a feel for how they are using it. We also give our users access to a test environment and encourage them to engage with capabilities after they’ve been shared during Sprint Reviews. That way, they get to have a play around at their own leisure, independently of more structured sessions. This also means we get feedback on an ongoing basis and not just during Sprint Reviews or dedicated UAT sessions.
Complimentary to this can be documentation to visualise the bigger picture. It’s helpful to remind stakeholders of where the business aims to head in order to contextualise the current iteration of working software.
Producing just enough and nothing more
ASOS believes in Acceptance Test Driven Development (ATDD) to help us safely and reliably achieve faster development, continuous delivery and deployment a few times a day (read more here).
Within ATDD, collaborative discussions called the ‘three amigos’, covering the three perspectives of customer, development and testing, ultimately aim to produce a set of acceptance tests. These, along with the acceptance criteria used to transform them into acceptance tests, provide a means for requirements documentation since they describe how the system will function and they are used to verify it functions as intended.
The produced documentation is just enough to meet the requirement and nothing more. Writing our acceptance criteria in the Given-When-Then format means that minimal further effort is required to transform these into executable test cases.
This collaboration — and corresponding lightweight documentation — between BA, developer and QA increases the likelihood of a higher quality product in comparison to just using detailed and formal documentation, which may not be subject to as much discussion or challenge.
Finally, let’s remember that our outputs (like code or training for our users) can bring about a means of self-documentation — if it’s done well, no documentation is required to actually explain it.
Do something great and do it again
There are so many ways to do simple documentation during a meeting or workshop. Just think, where would you be nowadays without Post-its?!
I mentioned in another one of my blog posts that there can be more harm than good in having no follow-up emails or photos of the output from a meeting or workshop. Following up is a quick and easy way of not only documenting but also communicating and storing outputs.
While we should always strive for improvement in what we produce, we should also have the confidence to stand by the saying: ‘if it ain’t broke, don’t fix it’. If you, or anyone else around you, is producing documentation in a great way, don’t hesitate to reuse it. This will not only save you time but will also start to create a standardised way of doing things. Equally, don’t be afraid to be lean and cut out bits you don’t need.
We’ve made some great progress to adopt this second value of the Agile Manifesto at ASOS Tech but we’re always looking for ways to better optimise our approach. I suppose just like those in the fitness world, there will continue to be a cycle of ‘bulking and cutting’ to ensure our documentation is lean while not lacking.
A reflection on the third Agile Manifesto value will be coming soon.
Joanne Whalley is a Business Analyst/Product Owner in ASOS Tech. Outside of work, she enjoys spending most of her time and money on restaurants, bars, music events and holidays!
