Why Jira tickets, code comments or meeting notes are NOT long term specifications?

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. 

A long-winded example

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-101 Add ability to make coffee via Wire.
  • Acceptance criteria: when pressing the “Make coffee” button, request the Wire backend to invoice 2.50 euros to the user. If the request is successful, espresso comes out of the phone audio jack. Else, show an error to the user.

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:

• WIRE-132 Add ability to make cappuccino via Wire.
  • Acceptance criteria: when pressing the “Make coffee” button, a popup asks whether the user wants cappuccino or espresso. If the user selects "Cappuccino" a cappuccino comes out of the phone audio jack. If they select "Espresso" and espresso will come instead.

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:

• WIRE-173 Check if the device supports milk frothing before offering to make cappuccino.
  • Acceptance criteria: do not show the cappuccino option if the phone doesn’t support milk.
• WIRE-175 Ask the user how much sugar they want
  • Acceptance criteria: After selecting the type of coffee, a popup asks the user their preferred amount of sugar. The sugar in the coffee produced by the phone matches the user's selection.

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).

• WIRE-876 Ask the user if they want decaf
  • Acceptance criteria: After selecting the type of coffee, a popup asks the user if they would like decaf. The coffee produced by the phone has an amount of caffeine matching the user’s decision.

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!

• WIRE-895 Download the sugar via the cloud
  • Acceptance criteria: When preparing a coffee, download the sugar from the cloud if needed rather than using the local phone reserves.

• WIRE-895 Build back-office payment system for Big Sugar Co.
  • Acceptance criteria: When producing a coffee, if sugar is used, make a separate request to the backend to send a payment of 0.01 euro per spoonful to Big Sugar Co. If the request is successful, proceed with the coffee production, otherwise show an error message to the user.
    
    
• WIRE-910 Reduce cost of coffee to exclude sugar
  • Acceptance criteria: when a coffee is made, the request to the backend should invoice 1.99 euro to the user for the coffee rather than 2.50 euro.

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!

• WIRE-173 Only offer to make a coffee if ingredients are available
  • Acceptance criteria: if there is not enough ground coffee, decaf, or milk to produce a given coffee, do not show the option to create the coffee type that requires that ingredient.

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)

• WIRE-922 Always put 1 spoonful of sugar in cappuccino
  • Acceptance criteria: when the user wants to make a cappuccino, do not ask for the amount of sugar. Instead, always add 1 spoonful of sugar.

Are all tickets under the same epic? No, as they came from separate initiatives, partnerships, and regulations, over a long period (perhaps years!).

Where is the specification?

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. 

• Wire decides to launch the Wire application on Windows Phones . The Windows Phone team shall implement the coffee feature “as it’s done on the other platforms”.
• Someone needs to do an audit of the solution implementation (perhaps a technical due diligence, an assessment of compliance, or to understand how a newly discovered vulnerability in the tech stack affects the product)
• There is a question on what should be the correct behavior (for example, after observing an issue in the application)

Consider in particular questions that have answers scattered across the summary of various tickets, for example:

• How do we decide how much sugar goes into a decaf cappuccino, and how much does it cost?

How would those people extract the specifications for “coffee making” from the Jira tickets?

• Step 1: Search for all tickets that mention “coffee”
  • there’s no better way to find them all, they are not in the same epic. Someone could have added a label (or component?) “coffee”, that would make it easier, but it’s a fragile solution as it’s easier to overlook it

• Option 1: Take the last ticket in chronological order, and refer to the flow described there
  • Problem: what if the last ticket didn’t have the full user flow (for example, “WIRE-910 Reduce cost of coffee to exclude sugar” probably doesn’t have the UX flows)
  • Problem: what if you picked an older ticket? I.e. “WIRE-922 Always put 1 spoonful of sugar in cappuccino” is the last ticket, but it does not include the word “coffee”, so you might miss it in a search and pick a previous one, where the user is still asked to choose the amount of sugar.
• Option 2: Go through ALL tickets, and build a mental model adding all incremental changes to get an understanding of the whole flow
  • For example, “WIRE-173 Only give option to make a coffee if ingredients are available” and “WIRE-173 Check if the device supports milk frothing before offering to make cappuccino” should probably be implemented by the same architectural component
  • Problem: missing even a single ticket will create issues
  • Problem: if the interaction between various requirements/changes is not immediately obvious, the final result might depend on individual interpretation

A better approach

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,

• A documentation section (probably multiple pages organized in a hierarchy) that covers the topic of “coffee” that is kept up to date whenever the specification related to coffee changes.
• The team always refers to that documentation

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

What about Meeting notes?

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

Conclusion

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.