Introduction

Delivering projects on time is challenging, but it's nearly impossible if your team estimates ambiguous items. Development tasks are broken down by a code deliverable, stories are broken down by feature deliverable. Which one is more likely to be accurate?

We have learned as an industry that shipping small batch sizes increases productivity, efficiency, and reduces inventory. We know that continuous integration and deployment are compatible with fewer bugs and higher quality. These lessons guide the principle of estimating development tasks versus stories. In order to do this, we must go through a tech spec process to break a set of requirements into technical tasks. These tasks can be mapped to user stories.

The tech spec will serve as a blueprint. The foundation of our task management principles. The basis for communication of project progress. A reference for the future. A way to parallelize and distribute work across a set of engineers. The empowerment for individual developers to autonomously solve problems.

When we are able to incrementally deliver value and estimate granular tasks, we are going to create more consistent velocities. This increases predictability for stakeholders, but more importantly allows us to accurately measure progress. That's what we are going after. We want to be able to accurately communicate where we are, where we are going, and adjust proactively.

Overview

• What is a story and a development task
• How to create a tech spec
• Loading your development tasks and stories into task management software
• Estimations, execution, reviews, and QA

What is a story versus a development task

In order to get into these principles, we need definitions. I want to be crystal clear with examples.

What is a story

A story in this article will refer to a unit of value to the customer or business. For example:

• "As a user, I can log into our application"
• "As a user, I can log out of our application"

What is a development task

A development task represents a code change that gets us closer to being able to deliver the story.

• "Create users table in postgressql"

The difference between a story and a development task is essential

The problem with estimating stories is that there is overlap between the development tasks to accomplish two similar stories. This creates communication overhead that wastes time. Even worse is that people may believe there is a shared definition, but it's actually different inside of each persons head. People may even disengage during the discussion because creating crystal clear definitions becomes more of a burden than they can cope with. Let's jump back to our example in the context of an estimation session.

"Okay now we are going to estimate the following stories":

• "As a user, I can log into our application"
• "As a user, I can log out of our application"

Discussion ensues. Is creating the users table part of the first story? The second story? Should we come to an agreement as a team that the "logging in" task comes first? This would make creating the users table is a blocker to the login story. We will need to increase our estimation for the log in task to accomodate for the users table work. The logging out story can become smaller since the users table is already created by the time we start that one.

Do you see the problem here? There is ambiguity about what units of development work each story entail. We haven't even talked about the task of creating backend routes and UI components. Those tasks also could fit into either story.

Creating Tech Specs

A tech spec will bear the burden of breaking stories into development tasks. A tech spec should break down development tasks down in such a way that the following statements are true:

• Task estimation is ambiguity free
• A developer who did not write the spec is able to work on the task
• We have a blueprint for future reference outside of task management software or pull requests
• The tasks can be worked independently in parallel by multiple developers

Let's examine each of these independently. We need to break down some walls and assumptions that may be brewing.

Task estimation is ambiguity free

Estimation should become trivial. A well broken down tech spec almost inevitably turns into 1s, 2s, 3s, with the occasional 5 for a task that is more unknown or complex. Rarely do you see anything else. It almost makes the estimation session a yawn fest. People tend to agree with estimates from the author of a quality tech spec. A well trained team with quality authors has the option to skip estimation. The author can provide initial estimates and the team can sign off on those estimates asynchronously. On a team with less shared understanding or experience, it is valuable to conduct a synchronous estimation session.

Lets break down our example stories into tasks. We must accomplish the following development tasks in order to enable users to log in and log out.

• Create users table with all the trimmings (columns)
• Add backend route that allows us to authenticate sign in requests
• Add backend route that allows us to log out
• Create frontend for the user to log in and log out

We might have a few others depending on our requirements, for example, maybe we are going to need a backing service such as redis. Perhaps our database hasn't yet been created. For our purposes we are going to skip these additional tasks, but they are included for illustration.

• Create database
• Set up redis server
• Set up lockout policies for brute force attacks

Fantastic. We have all of our development tasks.

A developer who did not write the spec is able to work on the task

A tech spec contains enough detail that another developer can complete the tasks. There is not a fixed amount of detail for a tech spec. All teams have different dynamics. The detail depends on your team and their skill, experience, and tenure. I have been on teams where all engineers have been present for 3 years as well as teams where everyone except me is brand new. Detail on tech specs for these two teams looks vastly different. For new teams or junior teams you may include links to a file or function in your source control (likely GitHub). I might provide a pseudocode implementation. You can define types and interfaces that the team must be implemented. You can stub out a PR. The development task may be to check out an existing pull request and fill in the stubbed functions. The author of the tech spec should assess the state of their team and provide the detail necessary for the team to execute independently. That's what success looks like for a tech spec.

We have a blueprint for future reference outside of task management software or pull requests

Is a tech spec is necessary at all? Can this detail just live in a task manager? Of course it can but I also know from experience that keeping each blueprints (tech specs) in a document provides immense value and knowledge over time. Onboarding team members, product managers, and also existing team members can easily find implementation details, and view comment conversations about tradeoffs. Document history can be examined. Tech specs in a quality cloud document editor (such as Notion or Dropbox paper) function as source control for your ideas and blueprints.

I have onboarded many engineers, PMs, and designers. These new team members take over domain areas that were previously overseen by ex employees. One of the most valuable resources for an onboarding team member are your specs and tech specs. They explain past product and technical decisions. Details about each story, and how it was implemented. There are often even have a specs / tech specs for multiple iterations of a business critical feature.

Put all these resources at your onboarding team member's fingertips, they will thank you for it. They give new owners historical context on why something was built the way it was. The knowledge at the time, the business goals, the technical tradeoffs. You will see the lights in their eyes and the heart emojis flowing out of their slack. Sigh with relief knowing that you don't have to try to communicate three years of knowledge over a single meeting or slack conversation. Check.

Leveraging your tech spec to fill in Jira ticket descriptions

The best way is to link out to your tech spec within a Jira task. Most document editors allow you to create links that jump straight to a header in a section. The Jira task has a title, an estimation, and a link to the relevant details in the tech spec. This ensures that you can continue editing and updating the tech spec without modifying your task. The future readers of the spec will benefit from any changes. An alternative is to copy the details into the task body. My challenge with this approach is that the blueprint (tech spec) can become out of date if the description is modified in the task manager.

The tasks can be worked independently in parallel by multiple developers

Can you build the login frontend before the table and backend are built? Absolutely. Working tasks in a waterfall slows development. It requires additional communication and coordination since team members may not be working on the same projects at the same times. Throw all of that out. Let one engineer build the login form as the other performs the backend task and database task. Your tech spec has the name of the route /users/login, right? It has the shape of the request and response, right? People should have what they need to build their respective component in parallel.

So what would stop us from implementing the login form in parallel? The ability to test it end to end and confirm it works? No problem! We can add one more development task.

• Confirm that login form works with backend endpoints (connect the wires)

Now we can do the backend and frontend simultaneously. Let your lead, tech spec author, architect, or excited frontend engineer take the final task. This is where the fireworks fly, and the highest complexity comes in. To connect the wires you must understand the system end to end.

Not every task must be worked in parallel. Some tasks are best worked as blockers to other tasks. That's expected. Just order the tasks from top to bottom in the tech spec in the order you anticipate them being worked. That's enough, particularly since each task is small enough that no single task should take a long time anyways.

Loading your development tasks and stories into task management software

Now that the tech spec and stories are written, we want to put them into task management. The tech spec author ought to own this step. The author is typically more senior and also understands the links between tasks most effectively. If a dev task blocks another dev task, create that link. I actually have a .csv template that I use to import my tasks into JIRA. The beauty of this is that if I have a tech spec with 30 tasks I just drop them into the CSV, mark the links between tasks, and upload. Boom, done. Let me know if you want the template! It's certainly the fastest and most reliable way of creating a set of Jira tasks that are linked together.

Marking links and executing on our tasks

Every development task gets marked as a blocker to its respective story. You can't test the story until each required development task is done. The development task approach allows us to examine the epics progress along the way. As each development task is complete we get a little closer to the epic being complete. Contrast that to when we execute and estimate on the story. Our progress was basically binary. Completing a table or backend route moved no tasks when we were representing our Jira work purely as stories.

Estimations, execution, reviews, and QA

Let's examine how this methodology ensures that each of these steps is easy.

Estimation

Estimation should be a trivial process now, with no ambiguity. Can people estimate how long to create a table, a route, and a frontend login component? Should be easy! Stories get estimated as a 0. Stories represent a unit of value to a customer, that can be tested. They are not related to the development effort required to enable the story for the QA team and customers.

Execution

Each developer can pull a task from the sprint. The details of the tech spec cover details according to the knowledge the team requires. Each dev task is standalone and can be worked on without fuss.

Code review is so much easier

One wonderful side effect of working development tasks versus stories is how much easier the units of work are to review. When you are adding a single route, a single component, a single whatever, the feature is broken up into logical units of delivery. My example did not include a feature with many components that constitute something larger, such as several new pages in the application. If you have ten components necessary to build 3 new pages, then each component can be a development task. The pages that stitch together the components can be development tasks. Everything can and should be feature flagged so that code can be merged to production. QA and Product teams switch on the flag to test the feature or incrementally roll out when they are ready.

QA

When stories become unblocked by their development tasks, they move into QA. We can release stories incrementally for QA. For example, let's say are going to deliver 5 new features that together make up a single epic. As each feature's development tasks are completed, each story can move into QA.

Wrapping up

We now have a framework to break work granularly into a set of tasks that are easy to estimate, easy to execute, can be worked independently, in parallel, and shipped without being held back in inventory. I will consider following up with an additional blog post of a meaty tech spec. I may also shares templates for product spec, tech spec, and stories. Through this process, estimations will become accurate, velocity more predictable, and delivery more stable. The lesson begins with working on development tasks not stories. I hope this has been useful for you.