Product Documentation with a Wiki

What is Product Documentation and Why is It so Essential:

When I refer to product documentation, it is the way in which the following are captured in writing – using a variety of content types, most commonly text and images that is for internal use:

• General Product Information: Overview and details about the product and its features that includes the product strategy and vision.
• Intakes: Details about intakes (“requirements,” problems, ideas, etc.)
• Discovery Initiatives: Content and data related to assessing potential solutions, any research, planning for delivery, etc.
• Other Information: Anything else that is important to have a record of, such as references to other resources, competitive products, etc. (that doesn’t duplicate its “source of truth”)

If product documentation is also needed externally, for customers and partners, it is recommended that it be put somewhere else, though based almost entirely on the internal documentation – it should be same or a subset of what is in the wiki.

There are so many reasons why product documentation is so essential. Here are just a few of those:

• There is too much product information to keep in your head.
• It is much harder to share information that isn’t documented.
• The less time a product manager spends sharing information, the more time they will have working on their other responsibilities.

What is the Audience for Product Documentation:

• Authors: Create the content for the purpose of being a reference or record for themselves or others.
• Collaborators: Review content so that they may make comments or edits to it.
• Viewers: View the content for the purpose of learning or answering a question about a product or its features.

What Features are Needed in a Tool for Product Documentation:

And I have found that the tool used for such documentation have the following features for the reasons listed, grouped by level of importance:

Capability	Description	Why	Importance	Notes
Common Content Types and Structures	Text, images, tables, in-document links/anchors, pre-defined styles (for structure)	Content is the essence of documentation, and it needs to be in its raw form to support other needed capabilities.	Essential	Although a tool may support images by “attaching” them as files, this capability excludes attaching documents, such as PDFs, as they are not the raw forms of content that would circumvent many of the reasons to use a wiki.
Flexible Information Architecture	Having the flexibility in the structure by which documents are organized, including being partitioned, if shared with other groups or areas of the business	Not all product documentation will be structured or organized the same way. And should a document management tool be shared across other areas of a business, there needs to be some degree of logical separation.	Essential	Pages are the most common form of breaking down documentation. And a “tree structure” is the conventional way of organizing pages, though it is important to be aware of other ways to navigate documentation, such as searching and AI.
Shareable with a Link	Anyone can easily share a link directly to any part of the documentation (e.g. a page)	This is the easiest and most common way of sharing documentation that is supported by most other tools, such as those used for email.	Essential	Deep links need to be support – those that go directly to specific part of the documentation, such as a page. Anchors in page could allow links to be even more specific – to a section of a page.
Version Controlled	Ability to track changes to see the history and revert to previous versions.	This preserves all changes that would otherwise be lost.	Essential	A more advanced feature related to version is the ability to a “diff” or the difference that highlights what changed.
Web-based	Ability to access, author and view content using any web browser or device	Minimal barriers to entry for authors and viewers – nothing to install (everyone has a web browser)	Essential	For mobile devices, the ability to view is important, but not authoring, which would be much easier to do with a bigger screen and keyboard.
Access Control	Ability to set permissions for viewing, commenting and editing content.	Ensures that only authorized users can perform certain actions.	Important	Common role-based permissions (from most to least permissions): Administrator Editor / Contributor Commentor Viewer
Commenting and  Collaboration	Those that review documents or work with others in the authoring of content, need the ability to make comments or edits.	Documentation is best managed as a team effort.	Important	It is best to allow for inline comments to reference very specific content.
Intuitive	Easy for authors and viewers to learn and use the tool.	Being difficult to learn or use would be a barrier to the adoption a tool.	Important	This is far more important from the perspective of viewers and collaborators, than it is for authors, which may requires some degree of training.
Limited Formatting	Only support basic formatting of content	Maintains consistency across documentation and improves readability and accessibility.	Important	Examples of basic formatting of text includes: bold, italic, strikethrough, heading styles, links, unordered lists, ordered lists, tables.   And advanced formatting that would NOT be supported includes: custom fonts, custom colors, multi-column layouts and sometimes alignment
Multi-media Content	Support for embedding or linking videos, audio, and interactive elements.	Including richer content can make it easier to explain and learn about more complex topic.	Important	This is particularly useful for sharing demos or animated visuals.
Searchable	Users can search for specific content across documentation.	Offers a faster alternative to using the navigation or document structure to find specific content.	Important	Advanced search capabilities, such as full-text search and filters, and a related feature is with AI RAG (retrieval augmented generation), which allows a question to be answered from the content within the wiki.
Templating	Ability to create and reuse standardized templates for certain types of documentation.	Ensures completeness of information and improves readability across documents of the same type.	Important	Some wikis have dynamic content features that may only be used with templates.
Change Notification	Ability to “watch” pages to be notified about any changes or comments.	Help to inform those that need to be aware of changes to a product or feature.	Nice to Have	The notification is most often facilitated via email, but some wikis may also integrate with other messaging platforms, such as Slack.
Content Generation (AI)	Assist with the editing of content (summarizing, formatting, rewording etc.).	Make it easier to author content.	Nice to Have	Note that AI is not recommended for generating content from scratch, as may not have the domain knowledge to do that.
Dynamic Content	Allow content that is derived from other sources to be generated (presented) dynamically.	Static content that is based on sources from other places could become inaccurate or need to be manually updated (if its respective source changes)	Nice to Have	Dynamic content could come from within the wiki or other external sources (which may require some integration). Some examples of dynamic content are: A list of PRDs (pages) showing the current status from the respective page In a page describing the research on an intake item, show the information for the associated roadmap item or intake
Integration	Ability to integrate with other tools for such things as user accounts (single sign-in), dynamic content or notifications	Make it easier for users to access the wiki, get relevant content in one place and stay aware of events (like changes or commenting)	Nice to Have	Examples of integrations: Active Directory (user accounts), Jira (project management), Slack (messaging).

Guidelines for Product Documentation:

Below are my recommendations for how to create product documentation, which should be adapted to what works best for your product management model.

General Guidelines for Product Documentation:

No matter what tool is used, there are some best practices for creating product documentation. These apply generally, for most types of documentation:

• Know Your Audience: Tailor the content, format and style to those that will utilize the documentation.
• Define Acronyms: The first time an acronym is used, show what it stands for. For example, when using a TLA (three letter acronym).
• Don’t Get Too Technical: Sometimes,  there is some technical information that should be included as part of product documentation, but most of those details should be maintained separately (by the engineering team).
• Highlight What’s Important: Use titles, basic text formatting, including highlighting for content that you want to stand out to viewers.
• Include Visuals: Diagrams, screenshots and other graphical content improve a viewer’s comprehension of information. As they say, “a picture is worth a thousand words.”
• Get Feedback: Have other SMEs (subject matter experts) review documentation as it is being created and allow others to add comments, all with the intent of making it better.
• Iterate: Product information should be updated as least as much the product changes, so treat it as “living” documentation.

Documenting Intake Details:

Sometimes referred to as “requirements,” though better considered as an intake, problem or idea, this information is about what is needed for and surfaced during the vetting by the product manager that ultimately determines whether it progresses through the discovery process. A common way of structuring that content is as follows:

• Background Context: Relevant information and data related to what follows, that helps establish the justification considering the intake.
• Overview of the Problem or Idea: A concise explanation of the issue or opportunity, including why it matters and its potential impact.
• Risks, Constraints and Considerations: Identifies potential obstacles, dependencies, or limitations that could affect feasibility or implementation. This may include mention of possible solutions, in a non-prescriptive way.
• Next Steps: Outlines immediate actions needed, including research, stakeholder discussions, or approvals to move forward. Or alternatively, if the decision is made to not take further action, with the reason.
• Notes and Assumptions: Any relevant details, open thoughts, or underlying assumptions that may influence decision-making.
• Questions: A list of what questions need to be answered in order to make a decision about the intake or more forward.

Assessing Potential Solutions:

The most important part of documenting the assessment of potential solutions for a product or feature is adequately capturing what was done, the outcome and what in the former justifies the later:

• General Info: A meaningful name for the initiative or project and reference to the associated intake(s).
• Key Stakeholders: Identify who was involved and how.
• Plan: The same information that would be included in a project, including actions/tasks, the associated owners,  and timing.
• Outcome: A summary of the decision that was made – both what and why.
• Assets and Artifacts: This would include wireframes, visual designs, prototypes, etc.

Recommended Wikis for Product Documentation:

Based on my personal experience and research, the following wikis are recommended, which are also in the list of product documentation tools that provide all of the features categorized as essential and important:

Tool	Nice to Have Features	Comments	Links
Atlassian Confluence	Change Notification, Dynamic Content	This is a very common wiki that I have used working at several larger corporations. It has robust features and has the benefit of integrating with Jira (also from Atlassian). Its macros feature is very powerful, though has a bit of learning curve.	Website
Notion	Dynamic Content, Content Generation (AI)	My favorite wiki. Easy to learn and use. Simple, clean UI that excels at the basics. It inherently structures content as data that adds to is flexibility and powerful features. And it is a tool that could be for more than just documentation, such as roadmaps and tasks. Note that change notification does not seem to be a feature.	Website

Here is a screenshot from Notion showing some of its features on a page:

1. Search
2. Flexible Document Structure as Pages with Icons
3. Content – Text and table show, and also supports images and other types
4. Tool bar when selecting text showing basic formatting, commenting, etc.
5. Comment
6. Import and Export Content
7. Version history
8. AI features for content generation and answering questions from content

 Other Factors when Evaluating Wikis:

In addition to making sure a wiki has all of the needed features, here are other things to consider before making a decision:

• Costs: Licensing, hosting, etc.
• Support: Type, cost, SLA (service level agreement)
• Portability: Importing, Exporting, Backup and Restore

Using Decks, Presentations and PowerPoints for Product Management:

As a product manager, there is no doubt that you will need to create or contribute to presentations that include slides or visuals with product information. Those assets should be treated as referenced content – taken from the wiki, without being modified. By treating the wiki as the “source of truth” for all product information, it will be easier to manage in one place, share with stakeholders, and prevent the generation or propagation of conflicting information.

File Sharing for Product Documentation:

You may have noticed that file sharing is not listed as a capability needed from a wiki. That is because there are other tools that are better suited for that purpose. And although some wikis of features for attaching documents, such documents are best maintained in other tools optimized for file sharing, such as conventional file sharing and cloud-based tools such as OneDrive, Google Drive and Dropbox. If there is product information that is in a format that is better managed as file, such as a spreadsheet or artwork, they should be managed centrally using a file sharing tool and referenced from within the wiki (as a link).

Other Tools for Product Documentation that are NOT Recommended:

I fully acknowledge that there are other tools that can be used for product documentation and they may be suitable for some product managers, teams or companies. Though, I have tried and seen other tools used that haven’t worked as a wiki that are listed here with my thoughts:

Tool	Comments
Word Documents	One of the biggest problems with using Word is it inherent ability to be passed around and duplicated as a file that make it difficult to manage and control as a single source of truth. Some of this is mitigated by using OneDrive, but it is still falls short of the capabilities of a wiki
PowerPoint Decks	PowerPoint is a tool that best used for what is was designed for – to present content. While it can accommodate many types of content, it has the same problems as Word being a file.
OneNote	OneNote is a great tool for documentation up until it needs to be shared, tracked for changes and have a consistent structure, as it doesn’t support templates. I use OneNote a lot for personal note taking and sometimes a place to start creating product information that I later put into a wiki.