Working on a software project with an agile methodology means delivering constant improvements in small increments. This translates to frequent changes on the product level (what the product offers, how the user experience works) and on the technical level (how it works under the hood).
Organizations typically track these changes using a ticketing system, such as Atlassian Jira, where tickets describe what needs to be implemented. A common way of organizing tickets is to have a story ticket describing a new user flow, created by the product owner. Then, developers create sub-tickets that list what needs to change at the technical level to fulfill the acceptance criteria (for example, create new API endpoints or new database entities).
While ticketing systems are valuable tools for managing work in agile environments, they should not be viewed as complete documentation solutions. This article wants to demystify the idea that just by storing this information in tickets, we have documentation. Sure, at least it’s written somewhere, but this is not a long-term solution. These considerations apply to both product documentation and technical documentation. To create a sustainable documentation strategy, organizations must recognize that tickets alone are insufficient.
Imagine you are working on the Wire application.
Wire can already send messages. Now we are adding the ability to make coffee from your phone via Wire, with a premium payment.
A product owner creates the ticket:
Wire implements the feature quickly and correctly, and it’s a great success! One week later, we want to double down to make the feature even more amazing.
The same product owner creates the ticket:
Again, a great success! But shortly after the release, we discovered that some phones with a significant market share don’t support frothing milk, therefore they can’t make cappuccino. At the same time, many people are unhappy about the inability to select how much sugar is in the coffee.
The following tickets are created:
But wait! Some national-level regulations just came out, making it mandatory for coffee providers to always offer a decaf option.
The new product owner (yes, it’s a different person now).
And Wire just struck a partnership with Big Sugar Co., which will provide the sugar directly via the cloud, cutting costs for all users. It cuts the cost of the sugar to just 0.01 Euro per coffee!
Some customers complain they are billed even when the coffee is not produced because there is not enough ground coffee or milk available on the phone. This is a bug!
After some market analysis, Wire decides to fix the amount of sugar in cappuccino. Wire knows better than the users, how much sugar is good for them! (sarcasm intended)
Are all tickets under the same epic? No, as they came from separate initiatives, partnerships, and regulations, over a long period (perhaps years!).
We could stretch the example further, but you get the point by now. In agile software development, products and features often evolve organically, leading to a rich tapestry of changes and additions. Lets consider a scenario that illustrates this point particularly with the example of implementing a feature like coffee making across various platforms.
Consider in particular questions that have answers scattered across the summary of various tickets, for example:
How would those people extract the specifications for “coffee making” from the Jira tickets?
The Jira-tickets-based approach excels in task management, allowing for the tracking of specific tasks, bugs, and feature requests. It facilitates easy assignment of responsibilities, promoting accountability within the team. However, this approach has significant downsides, such as fragmentation of information across multiple tickets, making it difficult to get a comprehensive view. Additionally, it requires familiarity with Jira, which can be a barrier for non-technical stakeholders.
In contrast,
Simple to understand, not error-prone.
At Wire, that place is a wiki (our vendor of choice is Atlassian Confluence).
This structure is accessible to non-technical team members, promoting collaboration across departments such as Marketing or Sales, including people without experience reading code or navigating an agile ticketing system. It allows for version control, keeping a history of changes that makes it easier to track the evolution of specifications
Meeting notes are written notes (on Confluence, Google Docs, or as Jira comments) that document the outcome of a meeting or discussion. People do not update them as new conversations happen. Instead, new meeting notes (pages) are created, resulting in multiple notes covering the same or adjacent topics.
As soon as we have more meeting notes, they will suffer from the same shortcomings of Jira tickets. Meeting notes are an excellent starting point for creating or updating existing documentation. Key points from meetings should be consolidated into the documentation to ensure clarity and prevent multiple versions of similar information. Always take meeting notes
While ticketing systems like Jira are invaluable for managing work in agile environments, they should not be mistaken for comprehensive documentation. To foster a well-documented agile environment, organizations must invest in user, technical, and process documentation that evolves alongside the product. It is recommended to use Jira for task tracking while maintaining a centralized documentation section for specifications, leveraging meeting notes to inform updates rather than relying on them as the main source of truth. By doing so, they ensure that knowledge is preserved, easily accessible, and beneficial for both current and future team members.