From ideas to clarity: How we wrote our internal product documentation

Good internal documentation is like a map for people inside your company so that they can understand and navigate your business. It fosters a common understanding of important aspects of the business, bridging gaps between teams that may have varying levels of expertise.

When people have access to easy-to-understand instructions, guides, and tips, tasks become easier, and mistakes are reduced. New employees can quickly get up to speed, reducing onboarding time.

A notable 44 percent of employees express a desire for broader integration and utilization of internal communication tools. This goes to show that internal communication is poor or entirely lacking in some companies.

This article covers the theory and practicalities that we considered in creating superior internal product documentation. It also features common internal documentation challenges and actionable tips on how to tackle them.

What is internal documentation?

Internal documentation refers to documents, records, and information created and maintained within an organization for internal use only.

Its purpose is to create useful notes for employees to share. These notes ensure that everyone is aware of how things work. They provide guidance on how employees should do their tasks, as well as on the processes they should follow.

Internal documentation can cover a wide range of topics, such as procedures, project details, functional and technical specifications, and more.

Internal vs. external documentation

As opposed to internal documentation, external documentation is meant for sharing with people outside the company, like customers, clients, or the public. It can include user manuals, guides, FAQs, and other materials that help users understand and use a company’s products or services.

Types of internal documentation

Here are the most common types of internal documentation that organizations create:

Project documentation

This type of documentation focuses on the details of a specific project, including its objectives, scope, milestones, and timelines.

Policy/HR documentation

HR documentation covers company policies, rules, and guidelines. It can also include human resource-related materials like employee handbooks and codes of conduct.

Reference documentation

This kind of documentation provides quick access to additional information on a certain topic, often in the form of manuals, cheat sheets, or guides.

Process documentation

Process documentation explains step-by-step procedures for various tasks within the company, which helps ensure operational consistency.

Team documentation

Team documentation focuses on how a specific team functions and its goals, responsibilities, and workflows.

Technical documentation

This type of internal documentation explains complex technical details, such as software architecture, APIs, and hardware specifications.

Product documentation

Product documentation aims at describing how a product or service will behave from a user’s perspective and outlines its core functionalities and other business-level requirements.

Our approach to internal product documentation

At Touchpoint, our product managers ensure a smooth documentation life cycle. They understand that internal product documentation is essential for effective knowledge sharing and team efficiency. Why? Because they manage a feature-rich product and a large, remote team.

Let’s dive into the methodology of how we crafted our internal product documentation for the purpose of streamlining the development of our soon-to-be-lanched SaaS product, Touchpoint.

1. Creating the initial version

At the heart of our product documentation lies a creative and collaborative process. Product managers collaborate with designers to create mockups and prototypes of the user interface, along with detailed documentation.

This phase involves competitor research, design experimentation, and in-depth discussions about implementation details. We lay the foundation for a robust product positioning and a clear development roadmap by addressing crucial questions and aligning with the development team‘s feedback.

2. Peer review by another product manager

Before introducing the documentation to the development team, an internal review takes place among our product managers. During this crucial step, open questions and potential areas for improvement are identified and discussed. This peer review ensures that the documentation is precise, coherent, and ready for the development team’s assessment.

3. Introduction to the dev team

Based on the prepared documentation, the development team evaluates the scope of work required and seeks further clarifications. Our documentation is then linked to Jira stories, facilitating seamless integration with the team’s agile workflow. 

The process involves using feedback from the development team. This feedback is used to improve the documentation. Additionally, it helps to make the implementation process better able to reach the final solution.

4. Keeping documentation up to date

Documentation remains a living entity throughout the development and post-launch phases. Queries from developers and the QA team are addressed through Slack channels, and product managers are responsible for ensuring that clarifications are promptly reflected in the documentation.

We encourage team members to add comments to the document. We also encourage them to have discussions with developers and testers. This helps maintain a dynamic documentation ecosystem.

5. Structure of the documentation

The documentation uses user stories to explain the page or view. It also goes into detail about specific user stories. Rich with screenshots, it details the expected user behavior and clarifies interactions between various elements of the product.

Touchpoint product managers use interlinking to connect general components and rules, streamlining the documentation process and fostering application consistency across different sections. Each document contains a header including the most general information and external references about the documentation.

Internal product documentation challenges

Given the growing demand for internal communication tools, businesses (ourselves included) face certain challenges with their internal product documentation. Here are the most common ones.

Difficulty in maintaining relevance

Keeping internal product documentation up to date requires continuous effort. As software, processes, and strategies evolve, documentation can quickly become outdated. Ensuring that documents reflect the most current information can be a time-consuming task.

Accessibility issues

Making documentation accessible to all relevant team members is crucial. Yet, in larger organizations or those with distributed teams, ensuring that everyone has easy access to the right documents can be a challenge. This is especially true when documentation is scattered across various platforms or folders.

Inadequate customization

Different teams might have varying needs when it comes to internal documentation. Giving customized information to each team is a delicate task, as a universal approach may not meet everyone’s individual needs.

A lack of documentation images

Visual aids like screenshots, diagrams, and flowcharts can significantly enhance the clarity of technical documentation. The absence of such images can make understanding complex processes or setups more difficult for readers.

Examples of internal documentation platforms

The following examples of internal documentation systems demonstrate how effective cross-departmental communication can be implemented within an organization.

Atlassian Confluence

Atlassian Confluence is a popular collaboration and documentation platform used by various companies, including ourselves. It provides a centralized space for teams to create, share, and collaborate on internal documentation.

Teams can create pages for different projects, processes, or topics and include various types of content such as text, images, tables, and even code snippets. Confluence also offers templates for common documentation needs, like meeting notes, project plans, and knowledge bases. It also allows for integrations with other Atlassian tools, such as Jira.

Image source: Actonic.de

Limitation

One potential limitation of Confluence is that, without proper organization and structure, the abundance of information can become overwhelming. If not managed effectively, finding specific documents or information might become challenging. 

While Confluence offers a good foundation for documentation, some advanced features require integration with other tools. Such features include SSO (Single Sign-On), which requires integrations with SSO solutions like Okta or OneLogin.

Pricing

Their Free plan allows you to experience Confluence with up to ten users, 2GB of storage, and community support.

If you wish to include more than ten users or access additional support and storage, you have the option to enroll in a 7-day free trial of either their Standard ($5.75 per user per month) or Premium plan ($11 per user per month).

GitHub

GitHub, a widely used platform for version control and collaboration in software development, includes a feature called GitHub Wiki. This feature allows teams to create and maintain internal documentation directly within their code repositories.

Teams can create pages using Markdown, a lightweight markup language, in order to document project-specific information, coding conventions, development workflows, and more. The wiki is tightly integrated with the code, making it easy for developers to access relevant documentation and link documentation with code.

Image source: GitHub.com

Limitation

GitHub Wiki is useful for documenting software projects. However, it may not offer as many customization and formatting options as other dedicated platforms. Additionally, the wiki might not be as well suited for non-technical documentation needs, like HR policies or company-wide procedures.

Pricing

GitHub provides three pricing versions:

• The Free version
• The Team version costs $4 per user per month
• The Enterprise version is available for $21 per user per month

It also offers a complimentary trial period so that users can explore its features.

Google Docs

Google Docs is a cloud-based document collaboration platform that allows teams to create, edit, and share documents in real-time. It offers a simple and user-friendly interface for creating and organizing internal documentation.

Teams can work together on documents, keep track of changes, and leave comments. It is useful for different types of documentation, like project plans, reports, and sharing knowledge. Google Docs also integrates seamlessly with other Google Workspace applications, such as Google Sheets and Google Slides.

Limitation

Google Docs is flexible and easy to use, but it lacks the structure and organization found in specialized platforms like Confluence. Google Docs does not have built-in features like workflow automation or code version control. You may need extra tools or integrations for these.

Pricing

Business-level Google Docs comes with the entire Google app suite and is offered in four distinct pricing tiers:

• The Starter plan is priced at $6 per user per month
• The Standard plan is available at $12 per user per month
• The Plus plan is offered at $18 per user per month
• The Enterprise plan requires you to contact their sales department

Ready to craft your internal documentation?

As we continue to evolve and innovate, the relationship between our product managers and the development team remains a key driver of success. Using a proactive approach to internal documentation management enables us to create products that truly stand out in the market, like our soon-to-be-launched customer service platform, Touchpoint.

This article provides guidance on how to maintain up-to-date and user-friendly documentation for your team. It covers various aspects such as upkeep, accessibility, customization, and visual assistance.

Leverage Touchpoint to streamline your customer service processes. The platform allows your support team to collaborate, troubleshoot with ease, and onboard new members smoothly. The fully customizable user interface can seamlessly incorporate visual customer interaction elements to aid you in your journey to craft internal documentation.