Requirements Phase

2 min read /

This is when your team documents what users want and how you plan to deliver it within the product. Use this phase as an opportunity to begin your draft documentation. When a new feature or product revision is first considered, an epic is created and user stories are written, each of which include acceptance criteria. Like great documentation, these are not written alone. Once the first draft of the epic, user stories, and acceptance criteria are complete, the team should review each and provide feedback. This is a fantastic time to collect questions and assumptions raised by the team.

Let's look at these three major pieces of information and how you use each to map out the documentation you'll need to write:

Epic

An epic is a collection of user stories needed to meet a greater user need. It's important that you work with your team to write a rich description of the epic here to help in product development and also to bring into final documentation.

Epics typically map to a new feature section in your documentation, or to an existing section that will need to be updated.

For example: The epic "Equipment Inventory" maps directly to the creation of a high level concept topic titled "Equipment Inventory". The description of the epic becomes the first draft of content for the new concept topic.

Learn more about creating topics.

User Story

A user story is a short narrative of who the user is, what they need to be able to do, and why. User stories help any team member relate quickly with users and understand what tasks they want to complete. Starting from the user story, you can map out the capabilities to write about in your documentation

For example: Consider the user stories:

  • As a mission planner, I need the equipment load balanced so the rocket will fly correctly.
  • As a mission planner, I need a shareable list of needed equipment so the team can load the rocket.

These user stories translate to a few capabilities "Load Balancing" and "Equipment List".

Often capabilities map directly to page headings within the new feature concept topic, though they can also become their own sub-topic, if large enough.

Acceptance Criteria

Acceptance criteria are the conditions documentation must satisfy to be accepted by the user. From the acceptance criteria, you can directly map out the tasks to document so users can take advantage of the new functionality.

In the example, items in the acceptance criteria might be that a user can:

  • Add an item to the inventory
  • Add custom equipment subtypes
  • Modify items in the inventory
  • Generate an equipment list
  • Share the equipment list
  • Print the equipment list

You can either create separate task topic for each acceptance criterion or write them as subheadings in the feature concept topic, depending on complexity.