Product Documentation

Hero image for Product Documentation

At Nimble, we put an emphasis on the value of writing clear and concise product documentation. It is a process of discovery that will allow you to:

  • Showcase the expected business functionality, requirements, and logic
  • Identify cases or uncover missing UX
  • Discover and define technical dependencies, strategy, and roadblocks
  • Use the document as a voice for the Product Manager - sharing the importance and value of a feature with your development team and stakeholders

What We’re Not Documenting

To be clear, we are not writing a how to guide or a user manual.

Defining The What, Why, How, When, and Who

When properly executed, the process of documenting necessary information for a new product feature will help you to discover and define: The What, Why, How, When, and Who of a feature.

The Why?

Explain the use case for developing a particular feature and why it is beneficial for the business.

i.e. The business team wants to increase the average time users spend in our app, therefore, we will introduce a chat feature which will allow users to communicate with each other, thus keeping them engaged in the app longer.

The What?

Elaborate on what you want build.

i.e. Implement a chat box feature where users can communicate with other users.

The How?

At Nimble, we like to focus on 3 aspects that compose How a feature will work:

Functional - Explain how a feature will function.

*i.e. Each user will be able to start a conversation with any of their friends from their friend list. The converstation can be accepted or rejected by the other person. The user can have up to 5 open chats at once.

Technical - Describe how the feature will work on a technical level. We are not here to tell the developers how to build a feature nor is this a subsitute for their expertise. Rather, this is an exercise for the Product Manager to be able to describe to the client at a more detailed level how their product will function. The benefits of doing so are:

  • Turns you into a sharp investigator with regards to bugs
  • Allows you to perform QA on a more technical level
  • Easier to understand and translate technical questions into digestible answers for non-technical stakeholders
  • Ability to understand the technical feasibility and limitations of future feature requests
  • Provide solutions for hypothetical features
  • Allows you to be in-tune with the product on a business and technical level. You know exactly how a specific feature works at any given time

Visual - The old saying, “A picture is worth a thousand words”, could not be more true when it comes to visualizing a new feature. Use and abuse all digital resources at your disposal to illustrate How a feature will function.

  • Screenshots
  • Mockups
  • When documenting (conditional) logic use flow diagrams
  • If there are designs available then you must add a design to the document. It is very important that we capture and lock in the designs during this phase. If the designs, for whatever reason, change - we will be able to come back and reference the original scope

When Are We Documenting?

This is a discovery process. It is equally important to identify when is the right time to write documentation:

  • Before you introduce the feature to your development team
  • When a feature touches all platforms (API, Website, Mobile)
  • When a new module is introduced
  • When the client is attempting to convey what they wish to build - this is very important. Sometimes an idea sounds good in your head, but when you put pen to paper the value and feasibility of a potential feature is laid bare for all to see

Who Do We Document For?

When writing feature documentation we need to keep in mind our audience. The goal here should be to write in a manner that speaks to both technical and non-technical participants. This includes:

  • Clients
  • Developers
  • Other Product Managers
  • The documentation needs to be understood by both technical and non-technical teams. We need to write in a manner that could be understood by both parties without sacrificing pertinent technical details

Discovering Roadblocks (if any)

When writing product documentation, sometimes, you might get half way through the process of putting an idea on paper only to find out that there is a massive technical blocker or feasibility issue. This is something that might only be discovered with the process of putting everything inside a document. This phenomena is not limited to technical blockers as it can also be applied to business pitfalls. For these reasons, it is of the utmost importance to being writing documentation at your earliest convenience.

i.e. You want to implement login with Facebook, you discover during the documentation period that the market you plan to release it to has banned Facebook, therefore the value of the feature is very low.

Where to Document

There might be cases where the client requests that we write the documentation on their tool (e.g., Confluence). In such a scenario, the documentation organization described below remains true despite the source being different.

Notion is our primary documents and resources management tool. It’s only logical that our product documentation lives there, too, alongside all other project resources.

Organizing the Documentation

Each project should have one parent documentation page called “{Project name} Documentation” (e.g., Nimble Documentation) and it needs to be added to the “Resources” database for the project.

This parent page will contain the complete product documentation. There must not be any other top-level documentation page for the same project.

The benefit of using only one parent page for documentation is that Product Managers can easily share it with stakeholders without having to mess around with the permissions system.

The documentation’s organization within the parent page is at the Product Manager’s discretion. However, there are three guiding principles that Product Managers should follow:

  • Be generous with sub-pages to categorize the various product features, APIs, etc.
  • Follow the same hierarchical order as in the backlog throughout your documentation (i.e., module → feature) as much as possible.
  • Always think of making it easy to retrieve information in the future.

Linking the Documentation

Because the documentation lives in the busy “Resources” database, it must be linked to the project’s homepage for the sake of retrieving it quickly.

Link to a product documentation on the project's Notion homepage.

Sharing a Documentation

Should a stakeholder need to access the product documentation, the Product Manager must share the parent page only. Sub-pages will inherit the sharing permissions.

External stakeholders must be invited as “Guest” users with commenting privileges.