One of the most significant issues that comes up in every agile project is how the team works with documentation, especially with requirements. At the beginning of a project it might be hard to see how critical it is to have at least some sort of requirements written down as the project moves from concept to completion. As the complexity of the project grows over time and things change it becomes essential to have a source of truth to confirm with. Having history or requirements changes also helps managers and developers stay sane and better understand previous decisions made as they fade away in memory.

Traditional approach

In a traditional or waterfall project requirements are written up front. The project team creates large Software Requirement Specification, and no development work starts before it’s completed. The document represents the main truth source of the whole project and is updated as change occurs in the development lifecycle. If specification says something, then it’s considered truthful, and if the implementation doesn’t work as described, it’s considered to be a bug in implementation until proven otherwise. Errors in specification happen quite often and could lead to severe consequences in the project.

The problem with such specification document is that it’s too large for anyone to work with — it can easily contain more than 50 pages with a lot of sections and subsections and finding something specific in it by reading it through is so overwhelming that almost nobody does that until forced to. Managing versions of the specification is even harder, mainly if something like a regular Word document is used as a storage format. Google Docs that have history and comments improve process a bit, but the team still struggles.

User stories as requirements

Currently, the most widely used approach is using user stories as requirements and avoiding writing and managing large specification. This method works until you have so many user stories, both completed and in the backlog, that you as a manager couldn’t grasp the essence of the feature quickly (and thus nobody in the team does). Lack of details in user stories is often one of the primary sources of problems for developers as they don’t give a clear understanding of how something should be implemented, only a general idea of the outcome.

User stories are not software requirements. They put the user in the spotlight and provide context for the team to understand user intentions so that the team knows what and why they are building and what value it creates. User stories are just a few sentences of natural language that outline the desired outcome. They are the smallest pieces of work that can be implemented within an easily measurable amount of time and create tangible value for customers. They are too small to act as requirements.

Epics, features and user stories

Epics, features, and users stories are generic terms used in agile software project management. There are lots of ways to interpret them and almost any piece of software designs a process around them in their own way. You can find different definitions in the professional literature and on the internets so take my understanding of them with a grain of salt.

  • User story. As I mentioned about it’s the smallest piece of work that team can do to bring value to the customer. User stories are defined as two-three sentences in a simple language. An excellent example of a user story would be “As a user, I want to be able to log in with my email and password.” User stories describe what users or customers do.
  • Feature. Features tend to describe the wider functionality of the product. They consist of user stories, and usually, a feature is completed when all user stories it contains are completed. An example of a feature would be “Login” or “logout” or "password reset.” That would include plenty of small user stories that would allow users to do everything they need. In contrast to user stories, features describe what the product does.
  • Epic. An epic typically describes very abstract and vague functionality in the product. While features and user stories are more specific and testable, epics describe more significant conceptual chunks and need to be broken down into features an user stories.

This definition is far from standardized of course. Sometimes features and user stories don’t form a hierarchy or are interchangeable — e.g., we implement several features to complete a user story. But I prefer to have a hierarchy because it’s much easier to manage the backlog this way

Epics as requirements.

During the years of work, we found that epics are perfect middle ground for requirements for an agile project. They are not as big as full requirement specification would be, but they are much broader and detailed than features and user stories. It’s easy to create written epic description and connect it to the mockups created by UX/UI designers so that requirements are full.

Since epics are broken down into smaller pieces, it’s also easy to use burger slicing approach to split epics into features that span all layers of the product and bring enough value to the end users. A product manager or a business analyst can then mark levels of epic implementation in the epic requirements document to reflect the roadmap — we usually mark every implementation level with a separate color to navigate the document quickly.

Epic requirements document usually contains a lot of the details uncovered by the business analyst. For example, if you’re implementing user accounts epic that includes login, logout and password reset features you need to define what your general authentication strategy will be. Do you plan first to use emails and passwords to log in and then adding 3rd party login providers like facebook? If you do, a business analyst will tell you upfront that Facebook users often don’t have emails but have phone numbers, so your system should support that. If you take that into account from the very beginning, you will save a lot of development time later on.