The old days of software development (read: prior to the ‘90s) were definitely not golden. The process was creaky and cranky, and projects were managed as a waterfall. The cascade started with laying out the requirements, which were then designed and moved on to development and testing. By the time the juggernaut lumbered off to QA, the budget was often inflated—both in terms of time spent and hairs split.
The problem with such a model, as Fred Brooks pointed out in his iconic book, The Mythical Man-Month, was that projects often had unrealistic deadlines: You could not react to discoveries—a.k.a. bugs—as a team, and you were locked into a schedule before you knew exactly what you were going to build and what problems you might encounter along the way. The one thread that often clumsily bound all of the stakeholders together was documentation. Requirements and design documentation were developed, everybody signed off on them, and fingers were kept crossed for healthy outcomes.
Agile for today
When people think of software documentation, they often think of software manuals (or of half-empty wikis). But these are only the tip of the iceberg. In order to consistently deliver software on time and maintain multiple releases, teams need to maintain a large corpus of internal documentation—and that’s what we’ll talk about here.
Today’s software development largely hinges on agile techniques, the most popular among them being scrum. In a perfect world, small teams that follow scrum bite off only what they can chew. Design, development, and QA all work together on smaller projects, called sprints, leading to more compressed development cycles.
What happens to documentation as a result? Since agile techniques require agile documentation, and since bug-free software is the ultimate end goal of each sprint, there’s a treasure trove of documentation to be found in a tool that teams use every day: the bug-tracking system.
Jake Brereton, the head of marketing for Atlassian’s issue- and bug-tracking software, Jira, has noted this evolution. “When Jira first launched in 2002, its original intent was as a bug tracker. It slowly morphed into more issue tracking, and then, with the rise of agile, it became a full-suite project tracker,” Brereton said. In essence, bug-tracking systems like Jira have evolved to hold all of the necessary information related to software development. As Andrew Ofstad, cofounder of Airtable, another project-tracking system often used for bug tracking, put it, bug-tracking systems are now “a centralized source of truth.”
There are many different kinds of bug-tracking systems, many of which are nested inside project management tools, and they range from the very basic to the impressively complex. The basic ones tend to have predefined fields with specific uses and workflows. This can make them easy to use and quick to learn, and, if the tool fits your needs, a good choice. More complicated tools, such as Jira, are often infinitely flexible, and can allow teams to customize schemas and develop workflows to suit their organization and process. This level of flexibility can be just what the doctor ordered—but, depending on your specifics, it can also be overkill.
There are plenty of options out there, so how can a software development team best tame the beast and make these tools work?
Tell stories
The work that a scrum team does is represented as a list of tasks (for example, “add a pull-down menu for payment types”) and stories, which are user-level product requirements (for example, “payments can be made by credit card”) small enough that developers can estimate how much work they would take to produce. Team members decide which stories and tasks to tackle during the sprint. If you’re a developer, you might make changes to the code to create the pull-down menu and commit your changes to the central repository. If you’re on QA, you’ll test the resulting build of the product, certifying that the menu is working (or not).
To make a project management or bug-tracking tool work well for documentation, a good approach is to assign each story to a ticket. Add the documentation related to that story to the ticket. “That’s where code snippets could be attached, that’s where designs are attached, that’s where questions are asked. That’s where one can see at any given time where things are in a workflow,” Brereton said.
If your documentation is maintained in a web-based system, it might be easy enough to integrate it into your ticketing system by embedding URLs into the ticket body as a comment or in a special-purpose field—a method that might be sufficient for small projects. However, a more comprehensive product suite might come with a corresponding documentation management system already integrated and ready to use, so that you can jump directly from the ticket to the exact article inside a documentation page, and vice versa.
Before you proceed, a word of advice: It’s really up to you to figure out how to define a story and a task, and this will shape how your tracking, ticketing, and documentation are organized. A task is a small amount of coding work that a developer can estimate; a story is a user-understandable product feature (e.g., the credit card payment capability example above is a story, not a task). It will take numerous tasks to make one story work. A QA professional will usually test an entire story, not one individual task.
“A lot of project management tools are rigid, with everything revolving around the notion of a task that has a title, a due date, a single assignee, and a text field for a description,” Ofstad said. “This may work for [smaller projects], but [often] work is much more nuanced and multidimensional and doesn’t fit properly into what the designer of the software conceived of [as] a task.”
In other words, you may say potato, and I may say potahto, but you and I need to agree on what a potato really is.
Follow the breadcrumbs
During a sprint, designers are designing features, developers are writing code, and all of the artifacts are evolving and changing. A given release of a product typically contains a number of completed stories, with their corresponding designs, code, and tests; it may also contain in-progress stories, containing the backlog at varying stages of completion. All of this needs to be tracked so that QA testers are not wasting their time on features that are not ready for testing.
In order to follow breadcrumbs, someone needs to leave a trail of them. In practice, this requires integrating the source code revision control system, e.g., GitHub, into the ticketing system. With a product that allows for integration, like Jira, this can look like a developer writing a comment that refers to the Jira ticket every time a commit is made, and Jira showing the relevant commit that has been made. Such integration leads to traceability. Later on, if somebody wants to figure out if a particular product fix made it into a release or not, they can follow these breadcrumbs.
When you make a release, say at the end of two or three or ten sprints, the source code control system should now show you all of the commits that went into it. If you’ve made sure that your commits point to the tickets, you can follow them and find out which stories are part of the release.
Everybody on the same page
Bug-tracking tools have evolved into the one tool that everybody works with. They’re the go-to place for the truth and often a central repository for internal (though not customer-facing) documentation.
There are other tools for product managers or UX designers, but project and bug-tracking systems enable collaboration and serve as a central repository for documentation among disparate teams. This can extend beyond the software development cycle. At Pandora, for example, HR uses Jira to onboard new employees and track all HR requests; Marketing uses it to manage all of its projects, including newsletters and collateral; Legal uses the system to track legal issues and review contract requests from across the organization; and Facilities uses it to track and manage new employee setup at workspaces. A similar system could be applied to any number of project management or ticketing tools.
“It’s way more about the culture than the tool,” Brereton said. “The tool facilitates whatever culture the team wants to build, whatever workflow they want to build, so it’s very important that the team first clearly sets out what they’re trying to achieve and how they want to work best.”
Don’t throw in the kitchen sink
A problem with using bug-tracking software for documentation is that people often err on the side of caution in terms of which pieces of information they include. Essentially they throw in everything, including the kitchen sink.
Most ticketing systems were not really designed for documentation but for project management, including tracking and collaborating on bugs. As people add comments, a ticket can accumulate a lot of notes on customer context, steps taken on an issue so far, possible hypotheses for debugging, false starts, email trails of conversations with field engineers or customers, and repeated status updates—so much detail that it can be hard to follow. Because of this tendency to wind up with a low signal-to-noise ratio, the verdict is still out on whether bug-tracking systems can be efficient repositories for documentation in the long run. Sure, they’re great for short-term sprints with a few dozen stories, but years from now, can one really use all that information without sustained, periodic house cleaning to extract meaningful reference documentation?
Different teams develop their own ways of dealing with reference documentation. For example, Optimizely, a company that makes customer experience optimization software, has two types of documentation, which can be loosely labeled as casual and formal. Casual ongoing active discussions and collaborations are recorded on Google Drive and can be referenced by the bug-tracking software as needed. The company uses Confluence for information that has “an air of permanence,” but not so much for “information in immediate flux,” said Dae-Ho Chung, engineering project manager at Optimizely. “If features are customer-facing, we have tasks in Jira to create public documentation and use different CMS tools to deliver finished documentation to our customers,” Chung said.
In today’s world of agile software development, an organization’s bug-tracking software has evolved into the single repository for critical internal documentation relevant to all of the product releases past, present, and future, for all stakeholders, from product owners and field and sales support teams to every developer, designer, and tester. The customizability, flexibility, and visibility these tools offer makes them an essential part of an engineering team’s workflow—if you use agile methods effectively and improve your team’s workflows over time. Effort spent on these tools to enable the workflow you want, and to integrate them with your other tools, is effort well spent. But as the tickets pile on, be prepared to put in the work to separate the noise from the truly valuable nuggets of reference documentation. We can automate a lot of things, but the need for an intelligent curator is not going away. Nevertheless, nimble bug-tracking software goes a long way towards delivering agile solutions for necessary internal documentation, and plays a vital supporting role in the software development process.