Confluence is a great platform for public-facing product documentation. There are lots of features and add-ons to help make pages that customers engage with and keep coming back to. This article explains how to use Confluence for documentation and make it awesome in six steps.

Step 1: Create your Confluence documentation space

Get started by selecting Spaces → View all spaces → Create space.

Choose Documentation space. This has a custom overview with a search box that will allow users to search just your documentation space. It also has macros for recently updated pages, featured pages, and popular labels on the home page.

Give your space a name and click Create.

Confluence tip: build out your space before making it public
You will need to make your space public by granting anonymous access to it. But you should build out all the main pages of your documentation before you do that. Once your space is public, you’ll need to restrict page access every time you create a new page, so that customers don’t see any half-finished drafts. So you may as well get the bulk of it ready while your space isn’t public. (Granting anonymous access is covered in step five.)

Step 2: Decide on content and how it will be organized

The most important area of your Confluence documentation is going to be a user guide, with pages offering step-by-step detail on how to use your product. There should be a page for every function of the app. You could also have a “Getting Started” guide with installation and licensing information.

Use cases and examples are popular. Customers will already know what they want to use your app for, but they may not know how. Use case pages make the functions of your app real, tangible, and relevant. They can also demonstrate additional ways of using your product that a customer may not have thought of, allowing them to extract more value from it.

You may also want to add a product roadmap so that customers can see what you’re working on and what features they can look forward to.

Finally, consider pages dedicated to troubleshooting, FAQs, settings and admin information, and support/contact details.

Once you’ve decided on content, organizing it should be relatively easy. Consider your page hierarchy before you start and which pages should be nested under others. Make your page tree logical and your pages easy to find, e.g. don’t hide a general FAQs page in your user guide. Create a separate “Getting Started” area because that’s where new users will go first. Keep use cases separate as well because customer may want to read those before they dive into the user guide and explore the features.

Confluence tip: links and labels
Make it quick and easy for customers to find what they need by adding plenty of links to other Confluence pages, and even to other sections on the same page. You should also consider labeling your pages with important keywords. Then you can use the filter by label macro to provide customers with a list of related pages that share a particular label or set of labels. Have a read of Atlassian’s page on how to use labels to organize your content for more detail.

Step 3: Make it consistent and easy to create/update pages

Consistency in page layout and design will make your Confluence documentation easier to understand, quicker to consume, and more professional to look at. All your how-to guides, for instance, should have similar amounts of information in similar sections on the page.

Confluence’s page templates ensure consistency and aid efficiency at the same time, making it quicker for technical writers to create new pages and update them later. There are a couple of Confluence documentation templates that come out of the box, including a how-to article and a product roadmap. But you may want to create a set of custom templates of your own.

Another way of making pages quicker and easier to create and update is by reusing content. If, for example, you’re going to use the same word, sentence, paragraph, image, product version number etc. on multiple pages, just create it once and reuse it on other pages.

Confluence offers an excerpt macro (define a reusable section of text), an excerpt include macro (add the contents of an excerpt to a page), and an include page macro (add the contents of a whole page). These features save you from typing the same thing over and over, and ensure that you only have to update the info in one place when something changes.

Confluence tip: templates and admin permissions
To create a customized Confluence documentation template, you need to be a space admin. However, if you don’t have admin permissions, you could still create a blank page with create a blank page with lorem ipsum text and macros, which can be copied and used as templates. If you do this, consider adding a “templates” label so that they are grouped together and easy to find.

Step 4: Make it clear, concise, and easily digestible

Anyone learning how to use Confluence for documentation should consider this the most important step. If your information isn’t clear, your users won’t understand it. You’ll be inundated with the same support tickets about things that are in the documentation. If your information isn’t concise, your users won’t read it at all. No one has the patience or time for product documentation that’s overlong and bogged down in extraneous detail.

If either of these things occur, it means your documentation isn’t working. So, decide exactly what your users need to know, and what they don’t.

Of course, it’s not just about what you present, but how you present it. Confluence has a huge range of macros for making your documentation pages more digestible, including dividers, tables, expandable sections, and the tip, info, warning, note, error, and custom panel macros. You could also add a table of contents to help customers get to what they need quicker.

Confluence tip: Aura macros
You can enhance your Confluence documentation further by using Aura macros. Aura is an Atlassian Marketplace add-on that enables you to customize Confluence pages with backgrounds, buttons, cards, panels, and more. Its flexible features can make your product documentation better structured and more exciting to look at.

Step 5: Make it public

Once you’ve created all or most of your documentation pages and your space is ready for the masses, it’s time to make it public. To do this, you need to make your space available to anonymous users, i.e. anyone on the internet.

Granting anonymous access has to be done at the site level first, then at the space level. In other words, your Confluence admin has to decide whether any anonymous access to your Confluence site will be granted. Confluence admins can manage site-level anonymous access in the global permissions.

Once anonymous access is allowed at the site level, it’s up to the space admin of the documentation space to grant anonymous access to that space.

Do this by selecting Space Settings → Space Permissions → Anonymous access. Then select Edit and check the box for the View permission. You want your public documentation to be view-only by customers and users. Then select Save.

The public will now have access to all content within your documentation space UNLESS you place restrictions on specific pages, which you will have to do when you draft new ones.

Remember, once you’ve made your documentation public, customers will see everything, including any internal comments made while the pages were being drafted. So make sure you delete those before granting anonymous access. If you’d rather keep the page comments for reference, consider using an app like Spacecraft, which lets you hide native Confluence elements like comments (more details on this below).

Confluence tip: don’t get confused with public links
Anonymous access has some overlaps with Atlassian’s public links feature, but don’t get confused between the two. If you’re creating documentation, anonymous access is the feature you want. Public links is only suitable for sharing a single page, one at a time. Find out more about the differences between Confluence’s anonymous access and public links in our blog.

Step 6: Make it look less like a Confluence space

Although you can make your pages as attractive as possible with Confluence and Aura macros, they will still look like Confluence pages.

One drawback of using Confluence for technical documentation is that Confluence is primarily a document management platform for internal use. Although customer-facing documentation has become one of its main use cases, it’s never been Atlassian’s primary concern.

Here’s what a non-public space looks like versus a public space. See if you can spot the difference!

Basically, when you make a space public, all that disappears are a few icons at the top, such as the pencil-shaped edit button, and the Share button. Everything else will remain visible. So your customers will still see space settings, the Create button, page contributors, the last-modified date, page comments, inline comments, and the more actions menu, which gives the public access to page history. If one of your contributors no longer has a Confluence account, customers will see that too. All of this is information that should stay internal.

If you want your documentation to have a look and feel that reflects your brand identity, this is another area where Confluence holds you back. There are no customization options to stop your Confluence documentation looking like an Atlassian site. Again, because anonymous access is not the use case Atlassian are most concerned with.

To make your Confluence documentation look more like you and less like Atlassian, you’ll need an app like Spacecraft.

Spacecraft allows you to turn your public documentation into a website that matches your company’s brand and provide customers with a better user experience. It also makes your documentation cleaner and more professional by letting you hide native Confluence elements and potentially sensitive internal information.

Spacecraft also works well with Aura and Karma, which means you can customize and improve both the overall site design and the on-page content. By the time you’re done, you’ll have more consumable product documentation that won’t look like it has anything to do with Confluence or Atlassian.

Confluence tip: Unsplash images
Spacecraft has an integration with Unsplash, the free image website. This allows you to quickly add a background image from a library of over five million photos and make your documentation site instantly less Confluence-y.

To summarize (TL;DR)

• You can use the Confluence documentation space template to get started creating your product documentation, but don’t make your space public till it’s complete.
• The most important area of a Confluence documentation space is the user guide. Also consider use cases, troubleshooting pages, FAQs, a product roadmap, and support information.
• Make your page tree logical and your pages easy to find, and use links and labels for ease of navigation through the documentation.
• Base your documentation pages on Confluence page templates so that they’re easy to create and update in the future. You can use any of the out-of-the-box templates or simply create your own. You can also make pages easier to create and update by reusing content with the excerpt and include page macros.
• Make pages more digestible with Confluence’s native macros, and make pages more attractive, engaging, and better structured using Aura macros.
• Once your documentation site is ready to go, make it public by granting anonymous access to the space. But make sure you remember to restrict permissions on any future pages you create while they’re still in progress.
• You can make your documentation site look more appealing, branded, and less like a Confluence space by using Spacecraft, which allows you to theme your space and remove native Confluence elements.
• If you use Spacecraft in combination with Aura or Karma, you can completely customize your documentation so that no one will know at a glance that you built it in Confluence.

If you’re interested in sharing public Confluence documentation that reflects your brand and offers customers a better user experience, book a personal demo of Spacecraft or try Spacecraft free for a month.

---

• Confluence anonymous access vs public links: clearing up the confusion
• Change your Confluence theme to brand your public spaces
• How to hide Confluence elements from anonymous users
• 7 product documentation best practices
• Documentation from Jira to Confluence – How It Works with Autopage!