Feature Documentation

Hero image for Feature Documentation

Structure & Content

When properly executed, the process of documenting necessary information for a new product feature will help Product Managers to discover and define: The what, why, how, when, and who of a feature.

The Why?

Starting with the problem statement: what are we trying to solve? What are the objectives of this feature? How will it benefit the business?

The How?

The following three aspects are required to describe how a feature will work:

1) Functional Requirements

This is where Product Managers break down how the feature will function from a user perspective.

The content should be structured with adequate headings and bullet points to make the information easy to read.

2) UX/UI

The old saying, “a picture is worth a thousand words”, could not be more true when it comes to visualizing a new feature. Product Managers should leverage all digital resources at their disposal to illustrate how a feature will function.

  • Wireframes or Mockups
  • Illustrated Screenshots

If designs are available, they must be included in the document. During this phase, it is critical to capture and lock in the designs. If the designs change for some reason, the team will be able to refer back to the initial scope.

3) Business Logic

The business logic defines the rules and workflows that dictate how the feature must function, its boundaries, and all actions executed —manually or automatically— when in use.

Creating relevant diagrams (e.g. flow diagram, sequence diagram) is a very efficient way to describe the logic in a visual way. It makes a complex feature easier to understand, especially for non-technical stakeholders.

By describing the business logic using a flow diagram, Product Managers will more efficiently detect edge cases. When documenting a feature aimed at different user roles/groups, it is highly recommended creating a Roles & Permissions matrix.

Responsibilities & Workflow

The Product Manager is responsible and accountable for documenting new features and maintaining existing documentation.

Link to Project Documentation on Notion

  • When the Product Manager creates a new feature documentation from the template, the prefix [WIP] must be used. This means that the feature documentation is being worked on by either the Product Manager or the Engineering Lead.
  • When the Product Manager has scoped the feature, they should solicit a technical review from the Engineering Lead (EL) before presenting the feature to the squad. The Product Manager should notify the Engineering Lead on Slack and specify by when they are expecting to receive feedback.
  • The Engineering Lead should check the overall feature documentation. This includes verifying the business logic to ensure it is correct and complete and thinking about all edge cases. The goal is to catch most, if not all issues before the feature is introduced to the rest of the squad.
  • Once the feature documentation has been finalized, the prefix [WIP] can be removed and the feature documentation can be shared with the squad and client.

Feature Documentation Template

To maximize the efficiency of the collaboration between Product and Engineering, we developed our own feature documentation template. Standardization helps to significantly reduce differences in the way we document features, and therefore facilitates squad rotations.

# Problem Statement

Explains the why: What we are trying to solve? What are the objectives of this feature?

# Solution

## Functional Requirements

*Use bullet points to describe how the feature should work from a user perspective. Explain the benefits for the user.*

## UX/UI

*Attach UX flows, UI screen design, or other design material that helps to shape the feature.*

## Business Logic

*The business logic defines the rules and workflows that dictate how the feature must function, its boundaries, and all actions executed —manually or automatically— when in use.*

- **Include relevant diagrams** (e.g. flow diagram, sequence diagram) **or any other material** that helps to understand how the feature will work
- CRUD definition
- List potential edge cases

# Resources

*Include documentation to any external services like API that are needed for this feature to work*

Using the template

As demonstrated on the above screen recording, this assumes that the parent documentation page has been created. Once that’s done, the next steps are:

  1. Go into the parent documentation page
  2. Duplicate the “Feature Documentation template”
  3. Go into the page you just duplicated and give it a meaningful feature name
  4. Fill out the content in the different sections


See examples of Feature Documentation