Documentation Guide

Use templates in Confluence to create topic guidelines without restricting the writer’s imagination.

Confluence comments are a powerful little feature. They can be very simple or even contain the kind of rich formatting you use on a Confluence page. There are two different types of comments in Confluence – inline comments and page comments.

Writing your docs together with a teammate is a great way to improve your writing skills. With pair writing, you and a teammate give instant feedback on the content which helps you to produce content rapidly.

Conversations within your team can be a great way to collect feedback and iterate to improve your documentation over time – but what about your users?

As your team works together, having an automated workflow will allow you to follow a consistent process for writing, reviewing, and publishing your Confluence documentation.

Use the Excerpt Macro in Confluence to mark a portion of content on a page for reuse. This feature is best for marking short descriptions. The short description is a paragraph describing what a page is about and is meant to help users understand quickly if the content is helpful to them.

Once you’ve added content as Page Excerpts or within your Include Library, use macros to include that content in your documentation.

If you use Scroll Versions for Confluence Server or Data Center, you can manage an include library with multiple versions and languages.

In Confluence, create a rich collection of reusable content. This is known as an Include Library, made up of one or more spaces containing reusable content items.

When thinking about your content strategy, there are two options for handling variants of similar content are to display varying content in the same space, or in different spaces.

When you only want to display the appropriate variant for a given user, you can use content hiding macros on your Confluence page.

To use a different variant of content for your help center and print publishings, you can use the Scroll Only and Scroll Ignore macros in the Scroll Exporters apps.

For conditional content management, Scroll Versions give you the tools you need. You can display variants of content and entire pages based on one or more attributes.

If your team makes a product that’s always on the latest version, such as a SaaS app, it may be less important for users to have access to older versions of your documentation.

Use Confluence page and space versions to track changes and organize your versions of your content.

Scroll Documents enhances Confluence Cloud by enabling your team to manage and version your documentation collaboratively.

Expanding the functionality of page versions in Confluence Server and Data Center, the Scroll Versions app introduces the concept of true space versions.

Another approach to versioning is to use a single space for both authoring new documentation and publishing released documentation.

A great way to start managing space changes is by creating an initial Confluence space for your documentation.

For small collections of documentation, or pages where you won’t translate much content, writing all languages on one page may be an option.

For large collections of documentation in multiple languages, you can use a separate space for each language.

With Scroll Translations, you can write content in all languages within a single space, manage translations, and translate in Confluence Server and Data Center or an external translation management system.

The simplest ways to share your documentation online involves making some of your Confluence content readable online.

To make your documentation accessible and useful to your readers, you can turn your Confluence space(s) into an online help center or knowledge base.

If your team makes apps, you can provide a great experience for users by giving them access to the information they need right within your user interface.

Sometimes a good old document is just what your readers need.

Want to host your documentation on your own web server? Export it as an HTML site.

Learn the basics of creating documentation in any agile framework.

This is when your team documents what users want and how you plan to deliver it within the product. Use this phase as an opportunity to begin your draft documentation.

With your draft in hand, you'll begin working with the team to write full documentation. This phase is interesting, because the team is simultaneously building and documenting the product.

Test the quality of your documentation by having one or more people unfamiliar with the contents read it and provide feedback.

As part of a great agile process, your documentation is ready for delivery along with your product. Publishing can be handled using one or more approaches, depending on the type of product you make.

With the product and documentation in the hands of customers, you will continue to review and iterate to improve your content.

Make use of macros in Confluence to expand the capabilities of your pages and then add labels to quickly organize your documentation.

Quickly and easily add media to a Confluence page. Learn how to organize your images and videos, and maintain them over time to ensure consistency.

Use diagrams in Confluence to illustrate a complex process to help users more easily understand complex information.