Blog
5. November 2024 Marek Vejrosta

Confluence and Product Documentation

Today, many physical products no longer include printed manuals, but instead provide digital versions accessible via URLs or QR codes, often linking to a product website with a user guide.

Products created by small, medium, and large organizations alike require product documentation. Why?

 

Product documentation is usually provided with the product, detailing its usage, operating instructions, disclaimers, and other essential information. However, it’s a misconception that product documentation is just a leaflet or brochure in a product box. Product documentation is a much broader concept. It’s not solely intended for consumers; consumer-facing documentation includes the minimum necessary and legally required information, which varies significantly based on the product. The organization itself also needs to retain extensive product documentation. For instance, consider an automotive manufacturer. How much documentation must exist for a single vehicle from the design stage? You’ll only find a primary driver’s manual in the glove compartment. The same applies to software, where the provider holds the product’s design, source code, and infrastructure descriptions. At the same time, the user only accesses a manual, often available in multiple languages for a global market, despite the product being identical worldwide.

Product Documentation in Confluence

Confluence is an ideal tool for system documentation, especially for internal use within organizations. Employees with a Confluence license create documentation; team members with licenses can access it. We recommend utilising the Guest access feature if you need to collaborate on documentation with partners or subcontractors. This free access is limited to one Confluence space, allowing up to five guests per licensed user. Guests can view, create, edit, and comment on pages within the designated space.

An essential step in creating documentation is designing a well-thought-out space structure. One option is to allocate a dedicated space for each product. Permissions for licensed users and guests can be easily configured per space. Additionally, Confluence allows access to anonymous users, meaning anyone can access a specific space without an account. This approach can be used to publish user documentation for public access.

Today, many physical products do not include printed manuals but instead direct users to digital versions via URLs or QR codes, often leading to a product website with a user guide. However, web templates are less suitable for technical and extensive documentation. Confluence and other specialized tools provide better features for managing extensive documentation and streamlining user information distribution.

Confluence view Geodata for Jira Documentation

What Key Benefits Does Confluence Offer?

  • Version Control maintains individual documentation versions and allows comparison (showing additions, deletions, or changes). It tracks who made changes and when. Users can revert to older versions and continue editing.
  • Templates – Accelerate work and help maintain document structure.
  • Collaboration – Multiple authors can simultaneously work on a single document, add comments, and discuss content.
  • Advanced Search—As product numbers grow, so does documentation. Confluence’s search allows you to find documents by title and content.
  • Security—Internal documentation can contain valuable proprietary information that you wouldn’t want to let competitors access.
  • Backup – Protects against data loss, including any in-progress documents.

 

Clear Page Tree Structure with Page Tree Visualization

The Page Tree Visualization provides a simple and intuitive way to visualize and understand the structure of your pages in Confluence.

  • Simplicity – Users can insert the application macro into a page, and it instantly displays a process map.
  • Clarity – Users can see the entire process flow on the page at a glance.
  • Time-saving – No need to manually draw a process map in Confluence; the application generates it automatically.
  • Integration – This application seamlessly integrates into Confluence, allowing users to create, edit, and share visualizations across various pages and spaces.

 

Confluence view Page Tree Visualization for Confluence Diagram Documentation v2

 

Types of Documentation

System Documentation

  • System documentation is used “internally” by developers, designers, and other technical teams. It often includes diagrams, models, and other highly technical content. It can also have business-oriented sections for marketers, sales teams, and other roles. System documentation is not publicly accessible.

For software, system documentation may include:

    • Product Requirements
    • UX Design
    • API Documentation
    • Architecture Description
    • Source Code
    • Product Map
    • Test Plans

 

User Documentation

  • Provides end users with information necessary for successful product or service use. Depending on the target audience, guides may cater to technical or non-technical users. Examples include user guides, quick-start guides, and troubleshooting manuals.

For software products, user documentation might include:

    • User Manual
    • Installation Manual
    • Training Guide
    • Quick Start Guide
    • Troubleshooting Guide
    • FAQs

Creating Quality Product Documentation

  1. Identify Your Audience – Before creating content, Consider who will use the documentation, their expertise level, and its purpose.
  2. Structure Your Content – Organize, categorize, and segment information to make it easy to read and digest.
  3. Include an Introduction – If the document is extensive, start with a brief product description, even if the remaining content is highly technical.
  4. Be Concise – Only include essential information, avoiding unrelated or excessive detail.
  5. Use Templates – Reusing predefined templates can enhance efficiency by including clear instructions for document authors.

Where to Create Product Documentation?

There are many documentation tools available. Which one should you choose? Here, we focus on Confluence, but your choice depends on factors like:

  • The type of documents you need to create
  • Whether you need to distribute documents internally or externally

You can also enhance Confluence with the Refined for Confluence app. This extension introduces a “Site” view that acts as a hub, grouping multiple spaces or linking to external resources. It includes a homepage editor for admins to set the theme and customize icons, fonts, and more.

 

Marek Vejrosta

Atlassian Consultant

If you need help from experts with the implementation or setup of Jira and Confluence or advice on how to use them most effectively in your company, don’t hesitate to contact us.

Our Atlassian Solutions

Similar projects