Let’s talk about documentation in Scrum
Is there really a place for documentation produced by Scrum teams?
As organizations started to adopt agile frameworks, there was a big shift in focusing on delivering software and less on technical documentation and specifications. Based on one of the values of the ‘Agile Manifesto’, ‘Working software over comprehensive documentation’, the specification of requirements has been reduced to as minimum as possible, if any.
That was a huge misconception in organizations that adopting agile meant their projects didn’t need any documentation at all. Organizations interpreted the value from the Manifesto too literally, by focusing on the part of delivering software and completely ditching out any kind of documentation. The interpretation was that only the parts from the left bring value and the ones on the right had to be abandoned. They chose to skip the point of the Manifesto “…while there is value in the items on the right…” and only followed “…we value the items on the left more”. Of course, that’s not the case for every organization, but if your organization is skeptical about documenting, this article may be interesting for you.
That proved wrong in many cases. Just to name a few:
- A feature developed by someone who has left the team and the business need or rule behind it is not easily known
- A feature asked by a stakeholder a long time ago and not the stakeholder itself remembers the details of the need behind it
- A change in market behavior or law that needs the previous rules to be revisited
When facing the challenges above, many teams struggle if these issues are not documented due to the “no documentation” approach.
What the Scrum Guide says
However, teams using Scrum make use of some form of documentation. They just come in the form of artifacts and their commitments.
Per the Scrum guide, there are 3 artifacts:
- Product Backlog: “…an emergent, ordered list of what is needed to improve the product.” (Source: Scrum Guide, 2020)
- Sprint Backlog: “…the set of Product Backlog items selected for the Sprint (what), as well as an actionable plan for delivering the Increment (how)” (Source: Scrum Guide, 2020)
- Increment: “…is a concrete stepping stone toward the Product Goal. Each Increment is additive to all prior Increments and thoroughly verified, ensuring that all Increments work together. In order to provide value, the Increment must be usable.” (Source: Scrum Guide, 2020)
Then, each artifact “contains a commitment to ensure it provides information that enhances transparency and focus against which progress can be measured” (Source: Scrum Guide, 2020). In practice, this “information” is also a form of documentation. Each artifact’s commitment is:
- For the Product Backlog, is the Product Goal: “…describes a future state of the product which can serve as a target for the Scrum Team to plan against”. (Source: Scrum Guide, 2020)
- For the Sprint Backlog, it is the Sprint Goal: “…is the single objective for the Sprint”. (Source: Scrum Guide, 2020)
- For the Increment it is the Definition of Done: “…is a formal description of the state of the Increment when it meets the quality measures required for the product”. (Source: Scrum Guide, 2020)
We can say that, if teams are using Scrum, at a minimum they are documenting the artifacts and commitments above.
Beyond the Scrum Guide
To come up with products that deliver value may imply work beyond the scope of a Scrum team. This bridge between the team and what’s outside the team is usually the responsibility of the Product Owner.
There are then other artifacts that, although not part of Scrum, might be useful to bring the team’s work in the right direction. Any team wants the features they deliver to bring value.
At a strategic level, being able to document a Vision statement and/or the Product Strategy, and have it visible to the Scrum team, together with the Product Goal, is useful to give context to the team about their mission. Who doesn’t like to know the answer to the question “So, what does the software you’re working on serve?”
The Vision Statement provides a high-level, overarching description of what the product is intended to achieve and why it exists. The Vision Statement is typically timeless and doesn’t change frequently. It may be used together with or separated from the Product Goal. It relates to the Product Goal that the Scrum team defines for its product, acting as an actionable objective that aligns with the vision. The goal of the Vision Statement is to provide purpose and strategic direction to the product. Vision is sometimes an inspiration for the Product Goal.
To write a Vision Statement, it should include a short description that helps to understand what the product is, what it’s not, who it’s for, and how it’s different compared to the competition. Just like the example below:
We may then document our product at a more tactical level, which is to say in a smaller time frame than the strategic level mentioned above. An example of another artifact that might shape the Product Backlog is a Product Roadmap. This one also falls under the responsibility of the Product Owner. The features of the product are planned and placed on a board to communicate direction and progress toward the vision. The order of features from the roadmap is then reflected in the order of backlog items in the Product Backlog. Three commonly used roadmaps:
• Goal-oriented product roadmap,
• Now-next-later roadmap, and
• Story map.
Closer to the teams, i.e. closer to the operational level, any relevant information is passed on in little chunks — at a Product Backlog Item (PBI) level (e.g. stories). Such items are split during refinement sessions so that they can be part of a Sprint. As PBIs do not contain extensive detail within them, but rather they act as placeholders for conversations between the Product Owner and the Scrum team, I find that a piece of crucial information to be included in a PBI is its acceptance criteria. They are a great way of passing information on how the PBI is to be built, but also on how it is to be tested.
Giving more details of a feature
Information about a PBI shouldn’t stop after the PBI is split and further included in a Sprint. Documenting what is discussed throughout the Sprint allows us to store what we learn about the PBI.
As mentioned at the beginning of the article, providing all the details we can about a feature is useful to record all covered business rules and that those rules are available for consultation by everyone — even if the ones that uncover them meanwhile leave.
Personally, discussing together with the team scenarios about the PBI, “behavior-driven development” (BDD)-style, has proven to be great at uncovering scenarios unidentified at the time of the refinement. Which is ok. And uncovering them means that more acceptance criteria are candidates to be added after the Sprint has started.
I have also found it useful to make rapid low-fidelity prototypes, both before refinement and during the Sprint. These prototypes are great for structuring thoughts about requirements. But also help uncover issues that we didn’t think of initially.
Finally, in my opinion, good old-fashioned models (e.g. UML) have a place here. They may be part of an attachment to the PBI. The conversations between the Product Owner and the Scrum team may have as an output a diagram that structures what was discussed. Or, even better, diagrams can be the trigger of those discussions. Moreover, they can be modeled collaboratively. For instance, I experienced in a project while discussing a PBI that included using a legacy API (“Application Programming Interface”), how great modeling together with the Scrum team a UML sequence diagram that showed how the new component would perform calls to the API and how it would make use of the data retrieved from the API.
Having a document repository structure
As a final target, I believe a good repository can be built, even if slowly and incrementally. Having such a repository at the end has great potential, in the worst-case scenario for exposing documentation post-mortem of a project or product.
A suggestion of a structure for this is the“Epic alignment” from Nils Janse’s book of the same name. It proposes a single source of truth about the requirements, in the form of a “lightweight” documentation that is based around epics. The structure that is proposed for this documentation includes information that is incrementally added to what we know about a given epic throughout the product development stages (namely, Ideation, Discovery, Prioritization, Refinement, Development, and Testing).
The structure of these documents allows us to follow the information about an epic, which user stories are included, and the details that are needed for their implementation.
