Product Documentation

Why Is The Team Documenting?

At Nimble, the team puts an emphasis on the value of writing clear and concise product documentation. It is a process of discovery that will allow Product Managers to:

• Showcase the expected business functionality, requirements, and logic.
• Identify cases or uncover missing UX.
• Discover and define technical dependencies and strategy.
• Discover roadblocks.
• Align with stakeholders (client and development team) on what to build and why.

Discovering Roadblocks

When writing product documentation, sometimes, a Product Manager might get halfway 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 phenomenon 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 begin writing documentation as early as possible.

i.e., The Product Manager wants to implement the login with Facebook feature. They discover during the documentation period that the market they plan to release it to has banned Facebook. Therefore the value of the feature is very low.

Who Does The Team Document For?

When writing product documentation, Product Managers need to keep their audience in mind. The goal here should be to write in a manner that speaks to both technical and non-technical participants (without sacrificing pertinent technical details). This includes:

• Clients
• Developers (and Engineering Leads)
• Other Product Managers

Where to Document

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

Note: even when the client requests the team to write the documentation on their tool (e.g., Confluence), the structure described below remains true.

Organizing the Documentation

Structure

Project's homepage on Notion
|___Resources
|______Product Documentation
|_________Feature A
|_________Feature B
|_________Feature C

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, which makes it easier to share with external stakeholders. There must not be any other top-level documentation page for the same project.

Guidelines

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 the documentation (i.e., module → feature) as much as possible.
• Always think of making it easy to retrieve information in the future.

Linking the Documentation

Given the importance of the product documentation, a shortcut must be added onto the project’s homepage on Notion:

Sharing the 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.

Creating a Feature Documentation

When the Product Manager is ready to create documentation for a new feature, they must create a new page within the Product Documentation parent page and start documenting the why, the business logic and much more:

Feature Documentation