The Whole Story: Technical Ticket Writing in Software Development
If you’re working on a distributed software development team alongside product and facilitation professionals, like scrum master, business analyst, etc… you’re probably prescribing your dev teams work using some sort of ticketing system, and the cornerstone of that system is usually a User Story.
What is a User Story
According to Atlassian, the company that makes JIRA:
A user story is an informal, general explanation of a software feature written from the perspective of the end user or customer.
The keyword here is general… usually, user stories don’t provide technical detail, and the implementation of the story is often left up to the individual developer that picks it up. This leads to the inevitable technical interpretation of that user story by the developer, and — if you’re building, say, a mobile app — this can mean significantly different implementations, and even different logic, across platforms.
The interpretability of user stories is a persistent problem among software development teams and there are lots of ways to solve it. Before we get to that, though, let’s talk a little bit about…
Why this is a problem
Estimating User Stories
Because of how general they are, user stories don’t provide any real depiction of the actual work that needs to be done, because they lack technical detail. But we we still expect developers to estimate that work based only on the user story — that’s to say, without knowing exactly what the work is that they’re estimating.
This, unsurprisingly, leads to wildly inaccurate estimates, usually in the direction of underestimating work. When you generalize something, it almost always makes it seem easier and less complex than it actually is. This, in turn, makes releases difficult to deliver on time; and time is, of course, money. Timeline changes always have a cost, which is why we spend so much effort planning out development in the first place.
In addition, since technical discoveries might not be uncovered until we’re doing the work, we may need to create additional stories, or new stories, or re-point old stories to reflect that new knowledge. This mean a lot more work for a lot of the team, both developers and others.
With that in mind…
What do we do about it?
Admittedly, in order to create user stories that a developer can really use, and that can be estimated with any accuracy at all, we have to do more planning, and engineers have to be more involved in that process.
Now, you might say, what’s the difference between doing that work up front, or as part of the development work of the ticket? At the end of development you spent the same amount of time/money… right?
Well, not really. Building applications nowadays generally means multiple teams building the same front end products on different platforms. But a lot of the work of technical planning benefits all of those development teams, not just one. In that sense, planning the technical solutions first can cut your overall development effort by a considerable amount.
In addition to that, if we do the planning up front, we can finally develop a high confidence estimate of how complex the work will be, which we can then translate into an achievable timeline.
Well, hold on, you might say (god, you talk a lot)… what kind of technical planning are we talking about, exactly? Well, I’m glad you asked.
A Two Part System
The first part of a robust technical solution design system is: Documentation.
Yeah, yeah… you don’t want to talk about that, because you’re all Agile or whatever, and the Agile Manifesto says we don’t care about documentation. Well that’s just another reason that Agile is Wrong, and besides that, what you’re doing probably isn’t actually agile anyway, so you really just should stop saying “Agile.”
What was I saying? Right, documentation. When you’re building one app a bunch of times, you need documentation, in order to keep all the different platform versions in sync. But, just like a lot of your code, your documentation should be Platform Agnostic — in other words, we don’t care what widgets or programming language you’re using; we care about what data sources you’re using, how and where that data is displayed, and how it drives the experience. These things are generally identical across platforms, and can therefore be thoroughly documented.
Technical Documentation acts as a guide for ticket writing, and a record of what we intend to do as well as, hopefully, what we’ve done. This is superior to ticketing alone, because the tickets are transient — they exist to facilitate the development, and then they are generally archived away in the done column and we never hear from them again. But a document is a long-lived, evolving thing that records what we intend to build, what we’ve built, and how it works. We can always go back to it to see if the product is performing to spec, and we can use it as a guide to do QA, and audit the app across platforms for consistency.
Finally, after we agree and document the technical details of an experience, then we can write the Development Story
User Stories are great, but not for software development.
So, don’t use them. There are no rules in software development (despite what your scrum master says)… if traditional user stories are useless (spoiler: they are) — don’t use them.
Instead, write technically specific Development Stories whose content mirrors the process and addresses the needs of development. For instance, when we build a new screen there are some predictable steps:
- Create empty shell classes for the screen
- build the UI of any new components on the screen
- Assemble the data modeling and API calls
- Compose the presentation logic
Therefore there are going to be three main development stories, and one for each new component. Those tickets are going to contain technical details that BAs can collaborate with engineers to capture, and the tickets will reference the technical documentation that was already written to describe the solution for the screen. And none of those tickets is going to contain the words “As a user.”
Of course, we can still maintain user stories to guide the overall development direction, but we’ll never ask a developer to move a User Story through a development process, or use it to try and estimate anything.
Managing the Work
I know what you’re saying — you pay developers to write code, not tickets. But involving developers in technical planning will accelerate the development they have to do, and reduce the scope of that development by eliminating the interpretability of user stories. So, you’re doing less development overall, and the work is better defined, which allows you to do it faster, and the resulting product is better. Also, the technical documentation keeps different platforms in sync, cutting down on individual implementation errors, miscommunications and errant differences in logical design.
Better, faster development more than pays for the reduction in developers time that is available to write code, since they are dedicating more time to planning.
Development Stories aren’t just good engineering, they’re also good business.