Two Blueprints for Agile Specifications

It will soon be ten years since I started doing project management in a form or another. One of the significant activities that I perform is translating consumers’ needs in requirements that can be efficiently converted into technical implementations by engineers. Over the years, I documented myself about most of the conventional methodologies of specifications from UML to User Stories in Waterfall and Agile context. The question of how I specify software often come in discussions, so I thought it would be interesting to share my current process here and to exchange about what you use on your side.

Core principles

1. The specifications are here as a reference for the developer but must also act as support to exchange around the feature.
2. The specification must evolve to follow the new version of the product.
3. They are not a static artifact consumed and forgotten.
4. The specification is here to detail the context in which the feature is implemented. Knowing the context (personas, system, goals, …) enables us to do all the micro-adjustment during the implementation in an autonomous manner.

Organisation

In an agile fashion, I group my features following this taxonomy:

1. An initiative is a group of related epics that, when delivered, will provide a new set of customers features. In my previous company, it was taking us between three and six months to deliver a full initiative on a product. Initiatives are a bit unusual and are not described more in detail in this article.
2. An epic is a group of user stories with a common goal. Usually, by convenience, I group all the user stories around the management of one resource like users or baskets in the same epic.
3. A user story is the single element of specification below which you cannot go. It is a feature or a subset of a feature that can be delivered to a customer. I try to cut my user stories as small as possible to be sure that if an unimportant element cannot be delivered in one sprint, its essence will be available in any case to a customer. For example, in resources listing, I always split pure listing from the sugar-like research and filtering that can wait for the next sprint.

Epic

I use epic specs to define as best as possible the context of the user stories an epic contains. To achieve that, I share the following.

• Purpose of the epic: Why is it there, and what do users want to achieve through its usage?
• Personas: This is the list of personas that will use the product. Code school in the first free chapter of The Elements of Web Design provides an excellent basic persona template that I advise you to watch.
• Characteristic of the epic: If the epic is related to the management of a resource, this is a table that summarises all the attributes of the resource. This is a direct legacy of the UML property system.
• Illustration: I illustrate the resource or business process modeled in the epic so the developer can see the business logic inside the software. Pictures, state diagrams, YouTube videos, prototypes, and competitive products are excellent sources of illustrations.

Google doc Epic Blueprint

User Stories

I use user stories to define as best as possible the way the system should behave without influencing the designer or the developer regarding the design or technical solutions. To achieve that I share the following things:

• User stories, while writing, I strive to define the received beneficial parts of the user stories as they are explicit in the intent of the features implemented.
• Source of the request, usually a customer ticket. This can give context the feature.
• be involved to be able to perform the user story
• The initial situation is how the system is before the use case starts, for example, resources registered or not, etc.
• Use case step by step, I write one line per action and try to define the nominal navigation path through the app without detailing it to let the UX part do its job.
• Exceptions, I list all the exceptions that I think could occur and how to manage them. I do not make explicit the trivial ones but focus on exotic cases like resources deletion conflicts, etc — all the things that the developer could forget to handle.
• , all resources created, resources updated, and events sent are defined here.
• Final pixels, if there are views involved in the user story, they must be ready when the implementation is started and linked to the user story as they give a massive context to the software that must be produced.

Google doc User Story Blueprint

Notes:

• When I model a process interaction instead of user interaction, I switch on a job story. The template is practically 100% identical.
• The estimate of the user story is not defined here as it is usually held by the ticket who enable the management of the user story.

Lesson Learned

Writing specifications is an investment that, as a PM, you must make to let your team members focus as autonomously as possible on doing their jobs efficiently while you work on other aspects like sales and marketing. Specifications will never remove all need for clarification and exchange around the product, but they will save you from a lot of back and forth with your team to ensure the product is right. Plus, they will hold the memory of arbitrations done in the past, which will help you avoid rechallenging choices constantly. The more time you invest in writing specifications, the better they will be during implementation. However, keep in mind that perfection is achieved only through practice. Personally, it takes me around two hours to specify a straightforward epic. This time does not include the exploration previously done.

I am very curious to know how you handle specifications, so if you share your methods in the comments section, I will be more than happy.