How to set up and implement your Product Documentation structure?
This is part 1 of a long-form series of setting up your Product Documentation.
If you’re already clear about the structure of your Product Documentation, feel free to skip over to the next part where I discuss how to write a Program Document for an Initiative or a Feature.
In my other series of articles on the process of building products, we discussed how Product Initiatives and Features are built to serve a Business Objective and briefly touched upon the structure of your Project Management tools.
We start with Projects and create multiple types of Projects to house our Issue Types of various types. We then divide these Projects into Boards of various types to track our requirements specific to Products.
A Direct-to-Consumer Organization’s Product Stack has the following types of Products -
- Consumer Products
- Partner Products
- Internal Products
- Core Products
When building Products and Features for any of the above types of Products, you’d need to manage the complexity of documentation of Product Requirements you may have to build multiple Features in parallel across multiple Products as well as build parts of the same Feature concurrently across these same Products. Thus, you’d need a structure to simplify this complexity for the following types of teams -
- Business Teams
- Design Teams
- Engineering Teams
- Product Teams
The Projects that we had set for our sample Product Stack were as follows —
- EasyRide Consumer
- EasyRide Agent
- EasyRide Driver
- EasyRide Admin Dashboard
Documentation Tool Organization
Any Documentation Management Tool should have a structure of organization that you should utilize to create, archive, and search for documentation history so far.
Let’s discuss the unit of arrangement of Documentation Management tools to understand their structure and hierarchy -
Grouping
You should be arranging your Documentation tool being used in such a manner that you group similar types of documents as well as documents related to similar objectives at the same place.
Depending on the tool that you’re using for the management of your documents, the following should be the arrangement units for the three most commonly used Documentation management tools -
Google Drive
Folder
Google Drive is arranged very similarly to the Windows Operating System with Folders as the unit for grouping similar documents.
Google Doc
Google Docs are the fundamental unit of Documentation in Google Drive and are the actual implementation of Documentation for your Product.
Confluence
Space
Confluence is organized into spaces that can be used to assimilate similar documents together in one location.
Page
Pages are the fundamental unit of Documentation in Confluence and are the actual implementation of Documentation for your Product.
Notion
Workspace
Notion is organized into workspaces that can be used to assimilate similar documents together in one location.
Page
Pages are the fundamental unit of Documentation in Notion and are the actual implementation of Documentation for your Product.
Grouping Count
Now, that we’ve discussed the structure of a Documentation Management tool and units of organization and implementation, let’s briefly also discuss the number of groupings that you’d need to create to exhaustively organize your documentation tool.
The number of groupings that you’d need to create for your Documentation Management tool should be equal and the same as the number of Product-Type Projects you need to organize your Project Management tool since you’d need to document Product Specifications on a Feature or Epic-level.
Please note that if you do some kind of brainstorming or writing to break down larger initiatives into Features or Epic-level, then you should also have a grouping for each Initiative-Type Project you have.
Thus, you’d have the following types of groupings —
- EasyRide Consumer
- EasyRide Agent
- EasyRide Driver
- EasyRide Admin Dashboard
You could also have some more generic groupings created for your other teams to document their specific SOPs and business Requirements, as well as their own custom Knowledge Base such as customer persona, user journeys, Performance, and Brand Marketing guidelines. You could also have the following further groupings —
- EasyRide Marketing
- EasyRide Demand
- EasyRide Supply
- EasyRide Operations
Documentation Tool Selection
All three tools discussed above have a basic free version that can be used for trial for some time. However, Google Docs are at the lower end of the degree of customization and easy editing possibility while Confluence is the most customizable and easily editable. I’ve found Notion to be somewhere in between the two.
Google Docs
Google Docs requires the least effort and learning curve since it’s exactly the same as Microsoft Word and covers up for most of the drawbacks of Word by being a little more flexible in terms of its quick-to-insert extra features such as tables, headers, footers, and table of contents.
Google Docs is pretty much not the standard to aspire to as far as Product Documentation needs are concerned since it lacks the diverse set of elements that need to be added to a document for different stakeholder types to collaborate on. Hence, it’s a good tool to get started with your documentation, but not good enough to scale with increasing team size.
Another disadvantage with Google Docs is that there’s no virtually no visible hierarchy of documentation and it’s hard to relate one folder with the next. It’s not intuitive to understand the complete structure and as a result, most old and dated documents tend to get lost and have to be retrieved by searching for the same on Google Drive.
Confluence
The learning curve for using Confluence is the most out of all these tools and every document requires publishing for your changes to be reflected to all your stakeholders. The one major advantage of using Confluence is its easy-to-use shortcuts and ease of adding different elements from ‘Code blocks’ to ‘tables’ and even ‘hyperlinked cards’. Confluence is the easiest to edit and the quickest to complete your document. It’s also quite easy to copy and edit tables which is the most used element of Product Specs.
The template library for Confluence is rich with standard document types. The capability of customization of documents and including some drawing elements on the same is lacking in Confluence and the latest addition of their Whiteboards feature has also not succeeded in completing this objective.
Confluence also allows for the linking of most other types of files such as Data Flow Diagram tool files, Design Tool files, and Technical Specification Documentation Files easily with a good user interface that renders the bare minimum UI of the linked file. One cool feature of Confluence is the capability of embedding Product Analytics Tools’ reports directly into the UI of Confluence which enables teams to just create a document to track their major KPIs instead of opening a lot of tools in parallel.
Paired with a Project Management tool such as Jira which is integrated directly with similar User Interface elements, Confluence can become very powerful by adding Jira Issues straight to Confluence documents with Issue statuses, Boards, and Roadmaps displayed embedded within Confluence only.
The one drawback with Confluence is that it can be great for creating static non-interactive documents but doesn’t work well with documents that can have interactive elements such as drop-downs and other widgets.
Confluence works best with large teams in scale since you can keep adding multiple pages within pages and hence, keep creating layers of related documents that are connected with one another in the same place.
Notion
The learning curve for Notion isn’t as much as Confluence and it has easy editable features for adding elements to the document. Notion has similar shortcuts as Confluence and the editor is equally easy to use.
Notion has a fantastic docs library that can be referenced for learning about the tool itself. It also has a rich template library for creating different types of documents with various types of widgets that are more interactive in nature than Confluence.
Linking other files mentioned above isn’t as easy on Notion as it is on Confluence and the rendering of the UI of these linked elements isn’t also great.
The one major drawback with Notion that I’ve experienced is that Notion is a little more difficult to edit and slower than Confluence. It takes a considerable amount of effort to create and edit existing tables on Notion and to re-arrange their columns or perform split and merge actions upon them.
The structural hierarchy of documents on Notion isn’t as visually intuitive as Confluence and therefore, it can become a little harder to find previous documents.
Notion doesn’t work as well on teams scaling beyond a certain size and though integrated well with other Project Management tools as well, the Use Interface isn’t embedded right into it and thus, is a little harder to operate as compared to Confluence.
Here’s a brief summary of the Documentation Management tools where I bucket each tool on the parameters mentioned above into three categories namely ‘Low’, ‘Medium’, and ‘High’ —
In conclusion, I’d recommend using an advanced editing tool such as Notion or Confluence depending on your budget since you wouldn’t be able to add more than 10 users to your Confluence without paying for users. If budget isn’t a constraint, then I’d recommend using Confluence for its crystal clear organizational structure, its fine-grained editor, and its ease and speed of writing a concise document, along with the capability of embedding multiple third-party tool links with their own user interface.
Document Types
In your journey as a Product Manager, you’d have most of your core time on Product Management occupied with ideating on future requirements and writing down major specs that your other stakeholders would require to be in sync. Following are the document types you’d need to write —
Program Document
A Program Document is a document that’s meant for instituting a new Program in an organization that requires multiple business functions such as Supply, Operations, and Product teams to come together to roll out a combination of Products and associated Services.
A Program Document in this case should clearly outline the business objective, the initiatives to be taken up with clearly defined owners, the user journey throughout the program of multiple user types involved, and the action items for each stakeholder. We’ll discuss this document in part 2.
Click here to download a free template of a Program Document.
Business Requirement Document
A Business Requirement Document is a basic document submitted by any of the Business Function Teams to build or enhance an existing Feature or Module by adding some more capability that’s not as complex as a Program but still needs to be built via Product.
A Business Document should clearly outline the business objective, and what needs to be built. We’ll discuss this document in part 7.
Product One Pager Document
A Product One Pager should document any new idea that needs to be built upon in the form of a Module or a Feature that needs the Business, Design, and Product teams to collaborate for a laid down objective. From the point of view of a One-Pager, Business Teams are passive participants since most of their actionables should be over at the stage of a Program Document.
In the overall timeline of building products, a one-pager is written towards the beginning to clearly define an objective, a success metric, the current scenario, and what’s required. It helps in identifying the ‘Why’ of a problem statement. We’ll discuss this document in part 3.
Click here to download a free template of a Product One-Pager Document.
Product Requirement Document
A Product Requirement Document details the specifications of the Features or Modules to be built. It’s a document that brings together the Design, Engineering, and Product teams for a common objective already defined with the relevant Product Success Metrics.
In the overall timeline of building products, a Product Requirement Document is written towards the middle to clearly include the User Experience and the linked features amongst different products if any. It helps in identifying the ‘How’ of a problem statement. We’ll discuss this document in part 5.
Click here to download a free template of a Product Requirement Document.
Product Events Document
A Product Instrumentation Document briefly discussed before in another series, lays out the events to be tracked in case of a new Feature or Module being built. It brings together the Engineering and Product teams to ensure that the decided success metric of the product measurement is being enabled. We’ll discuss this document in part 6.
Click here to download a free template of a Product Events Document.
In the overall timeline of building products, a Product Instrumentation Document is written toward the end to define the events to be tracked for all the users. We’ll discuss this document in part 6.
Here’s how I’d summarize each document type with the relevant properties —
Summary
Documentation tools can be of many types and should be selected on the basis of the parameters mentioned above but I’d recommend using either Notion or Confluence to always have a single source of truth for all your Product specs.
Even if your organization doesn't have much of a documentation culture, I’d still recommend you institute a culture of writing at least a Product One-Pager to bring different stakeholders on the same page.
Structuring your Documentation Groupings in the tool that you’re using will help you in searching archived documents, collating related documents, laddering iterations of similar types, and making the discovery of your Product easier.
In the next section, we’ll discuss how to write a Program Document to bring together your Business and Product teams to explore and operationalize an idea for fulfilling a business objective along with a free template to download for writing your own Program Document.
Do share your feedback with me at kshitj.saxena@gmail.com or connect with me on LinkedIn
