How much documentation is enough for an agile project?
Scrum doesn’t explicitly state what requirements are necessary to document during a Sprint or even throughout the project. This has led to some suggesting that there is, in fact, no documentation in an agile project. Nothing, however, could be further from the truth.
The Agile Manifesto
The Agile Manifesto is the basis on which agile methods like Scrum and Extreme Programming (XP) were founded. Part of this manifesto states:
Working software over comprehensive documentation
This doesn’t mean ‘no’ documentation, or that comprehensive documentation shouldn’t be created. It only states a philosophical preference.
This philosophy was born for two reasons. The first was the suggestion by the signatories of the manifesto over a decade ago that the most efficient and effective method of conveying information to and within a team is face-to-face conversation [1]. The second is the emphasis that modern agile methods is on the delivery of products, including working software, which is also their primary measure of progress [1]. As such, a Scrum team isn’t required to create documentation unless it is defined by the Product Owner as a Product to be delivered by the team.
Enterprise requirements for documentation
In previous engagements where Zen Ex Machina has transitioned projects from Waterfall to Scrum, we’ve been required to create the following documents in order to adhere to the organisation’s Prince2 frameworks for project management:
- Sprint plan
- Stage plan
- Test plans
- Quality plan
- Product description
In most cases, I’ve coached the Product Owner to describe this documentation and its associated acceptance criteria (“Definition of Done”) and then place it in the Product Backlog along with the other Products for the team to produce. In a few instances, particularly where the Product Owner is also the Project Manager, they’ve been the one to then create the documentation as part of the project’s reporting requirements. Aligning Prince2 documentation requirements with Scrum isn’t all together very hard, but it does take some experience to understand where the direct relationships are and when you’ve got to get a little creative. Fortunately, my experience has been that because Scrum is cyclic, and all of the major activities stay the same each Sprint, documentation like the Sprint plan, rarely change.
Some organisations still require, however, large requirements specifications to be created. I’ve come to find these are not terribly useful other than for a project’s steering committee who have been asked to sign-off on a project’s scope. I’ve come to find it more useful for documentation to be defined in systems like Microsoft’s Team Foundation Server (TFS) or in Jira/Greenhopper.
Using a systems approach, rather than storing requirements specifications in a Word Document, results in retention of the inherent traceability between user stories, Epics and the strategic scope, with associated tasks that reveal what was done to deliver a set of features. It also has the benefit of change control — where a document can become quickly outdated due to changes in a project, using a simple and easy to use system reduces the likelihood that information will be outdated, particularly if that system is used to record all of the project’s activities. And if you’ve configured things well, you can even produce paper reports for management.
When I’m coaching a new Scrum project, I rarely see documentation requested through the project management hierarchy down to the Product Owner. But there are some artefacts that I encourage my Scrum teams to produce the following: user stories; personas; wireframes; and architecture diagrams.
Use Cases and User Stories
I don’t write use cases any more. I do, however, find it very handy to write up all of my User Stories onto physical cards. This enables me or the Product Owner I’m coaching to take the cards to stakeholders and end-users to talk to them about upcoming Sprints and what to expect from them. Jotting down notes on them makes these the repository of knowledge for the Product Owner who then places them into TFS, for example, when it comes time to Sprint Planning. Until then, though, the cards are considered a work-in-progress, where TFS is the “source of truth“.
User Stories, however, might not be sufficient to detail what the Product Owner requires of a team. As such, a number of different formats for User Stories have emerged, Behaviour Driven Design (BDD) being my preferred one. BDD is more useful for testing than an ordinary User Story format and, because I use a Persona as the role, it contains traceability back to why a feature is useful or valued by an end-user.
Personas
When it comes to making design decisions, Personas make the perfect sounding board for a Scrum team. I use them to hold everything that is known about each distinct archetypal user group. I rarely now do months of user research about what users might value because I tend to leverage existing research from, for example, website statistics and marketing research, or publicly published data from Nielsen/Norman or Forrester.
Wireframes
I encourage the Scrum teams I coach to be multidisciplinary. This idea goes back to the original premise of Scrum as described in the New New Product Development Game [2] and enables different view points to contribute to a Product to not only improve the value proposition it offers its users but to also encourage the team to think smarter about the ways in which they approach their problems. Wireframes are typically the domain of UX practitioners and help to understand what layout of functionality will work best and how each screen flows from one to the next. I like to use wireframes during Sprint Planning in particular. These are just hand-drawn on the whiteboard so that everyone knows what is expected of a UI, and then the wireframes are photographed (most often just with someone’s iPhone) and then stored in the team’s SharePoint environment. I’ve also seen some of my team print them out and stick them on the wall to remind them of what to code. These often form placeholders for later discussions with the wireframes evolving with hand-drawn notes and post-its to capture the team’s understanding of what’s needed. On some occasions, though, I’ve put these into a document and then annotated them so that others can understand the design decisions made at the UI level. These have been useful to distribute to people such as the project’s business owner, but are rarely useful to the team themselves because their knowledge and understanding has come from collaboration. Unless a Product requires formal, pixel perfect wireframes such as those produced by Axure, hand-drawn wireframes work best.
Systems and data architecture diagrams
Understanding all of the touch-points between system entities and their associated requirements can be difficult. Implicitly knowing where data should pass between those entities is also sometimes confusing. They say a picture tells a thousand words so just like hand drawn wireframes, a context diagram or the like is an invaluable tool to capture the complexity in a way that is easily digestible by others as a reference guide.
Conclusions
They say that Microsoft Word is where requirements go to die. In my own experience, I’m tending to see documentation in both agile and traditional project environments using smarter tools to capture requirements and other forms of documentation that can both assist with team collaboration and cater to the needs of those people who will later maintain the system. In agile environments, my own documents tends to be fast and quick and written on a whiteboard rather than carefully crafted and placed in a Word Document. Documentation in agile environments, overall, are created because they exemplify the team’s knowledge and that’s where I’d prefer to focus my effort.
M
– – – –
1. Principles behind the Agile Manifesto. Online at: http://agilemanifesto.org/principles.html
2. Takeuchi, H;& Nonaka, I (1986).“The New Product Development Game” Harvard Business Review. Retrieved June 9, 2010.
