Collaborative documentation: Feature passports

Collaborative documentation with feature passports

Crafting digital products is an interdisciplinary process, a collaboration of product managers, UX designers, UI designers, developers, sales, domain experts, researchers, customer support, etc.

All help shape both the actual product as its culture. Multiple professionals work together with different tools and specific terminology, aligning visions and communicating between separate disciplines quite challenging. Feature passports can help lower those barriers.

Why use feature passports?

With many available tools for different roles, information might get lost or misunderstood between the different people involved. The developers’ API specification might not be useful for a stakeholder to know what the product is capable of. A feature passport is an accessible way for everyone involved to not only learn about the feature but also to provide enough information to start working on their responsibilities.

On top of that, feature passports bring the following benefits

• Everything that is documented is also traceable: from decisions made to answers we need to address.
  
• Even though a feature passport will contain a lot of text, writers are encouraged to include visuals. These visuals can come in different formats (wireframes, interaction models, database designs…) and come together in one place.
  
• Because writers do not have to know or learn a certain tool or technology in order to contribute, the whole team has a low threshold to contribute to the feature passport, facilitating multiway co-creation instead.
  
• More transparency emerges between the different stakeholders and involved profiles.
  
• Professionals all have different calendars and are (often) busy. They can read the feature passports at any time which do not require a meeting. Questions and remarks can be gathered asynchronously. This saves everyone several hours of (boring) meetings every month.
• I recommend writing in Notion or another documentation application as feature passports contain many words. Those tools often contain a helpful search feature, which provides a better search experience than going through all screens in Sketch or the comments in your code.

At Smooth Sailing, we use a template that consists of the following sections:

1. Value of the feature

Which questions do we answer here: Description of why we decided to make this change/include this and why it benefits our product. What problem does it solve? What was the goal we wanted to achieve? Who will benefit from it? Why should our customers care about this?

This section explains why this feature is included in the product. For example: Did the team include the feature based on user research or did we find a way to enhance the user experience? If nobody comes up with arguments to include here, the feature might not give any value to the user or the company, and the team needs to reconsider the necessity to spend (even more) resources for it.

Also for people who are not directly involved in realizing the feature, this section will create the context to better grasp the following sections in the feature passport and to honour the product’s culture in external communication (e.g. to (potential) users and texts on the website).

2. Metrics

Which questions do we answer here: When is this feature a success? How can we quantify this?

We welcome both usage analytics and business targets here. Those pieces of information not only tell what makes the feature a success but also inform developers or researchers how to set up the analytics systems and come up with hypotheses for validating respectively.

3. What’s our long-term vision for this feature?

What do we put here: Description of any follow-up changes that are planned to be made in the (far or near) future.

This is a welcoming place for features that are out of scope for the moment, but which are still interesting to revisit in the future. Do you sometimes park a discussion point or feature and never come back to it? Those kinds of items belong here, too.

4. Possible FAQ from users

What do we put here: A list of questions that can be expected from customers with an answer for them?

This section is not only for support to use as a source for copy-paste answers. This will teach the team about the issues users are encountering and the features that might need another iteration.

5. Define the terms used to describe this feature

Which questions do we answer here: How should we as a company talk about this feature, both internally and externally? What do we mean by each term?

Explaining each term related to the product helps with consistently using the right words in both the product and while communicating. For example, using the terms filters and effects for a photo editing application interchangeably not only confuses the users but also the professionals in the team. Having this glossary can decrease the number of mistakes and questions by both groups.

6. How should the feature work?

What do we put here: What is the flow? What does every button, link or field trigger or display? How does a user end up on the feature? (Links to prototypes, sketches, screenshots, … are encouraged).

This is the heart of the feature passport. The information here explains the behaviour of the application, an important topic for everyone involved. It serves as a manual of the application for the support team, a scenario for the stakeholders, or the flow of the application for the designers and developers.

7. How did we jump to this conclusion?

What do we put here: What research did we do to get to this solution?

If anyone ever nags about a feature based on data, just refer them to this section.

8. Known issues

What do we put here: Bugs or problems that we are aware of with the product or feature?

It is important to know which issues are known. Maybe you are the first person who has detected it or you get a support ticket for something that should not have happened according to the documentation. Either way, when a bug or problem is found and communicated to the team, it can start working on it while the team is aware of the issue.

9. Open questions

What do we put here: Questions we need to address in the next meeting

Sometimes proper discussions are necessary to reach the most optimal outcome. Team members who put something in this section might be blocked or have found an important issue. The open questions are helpful for making the upcoming meeting actually useful.

Downsides

• Everyone in the project can contribute, even the mole
• People often do not like documenting
• High maintenance: information, terminology, and definitions need to be consistent in all feature passports, open questions need to be addressed, updated, and checked… One update might require updating other feature passports.
• Writing documentation takes time. People might be documenting the same information multiple times in different places. The information is often already implicitly available via other existing artifacts (wireframes, sequence diagrams, user flows…).
• Quality depends on the writing skills of the involved people
• The writing style of several authors might differ strongly, causing inconsistent writing style in case “free-writing” types of tools are used (e.g. Notion, Google Docs…).