How to use Confluence for documentation: 6 steps to success
Share on socials
How to use Confluence for documentation: Six steps to success
Holly Aspinall
23 May 2024
8 min read
Holly Aspinall
23 May 2024
8 min read
Jump to Section
Jump to section
What is documentation?
Why is documentation important?
Why should you use Confluence for documentation?
6 steps for successful Confluence documentation
Make your Confluence documentation user-friendly, clear, and interactive with our six-step guide and examples.
Confluence is an incredibly versatile tool with a number of different applications. Whether it’s used as a company wiki, department hub or co-working space, Confluence is ideal for remote work and in-person collaboration alike.
But Confluence doesn't have to stay within your company. It can also be used to create technical documentation for external users of your products. Here's how to make your Confluence documentation as clear, user-friendly and interactive as possible.
What is documentation?
The term “documentation” (also known as technical documentation or software documentation) covers a wide range of information that's organised into -surprise! - documents. Documentation comes in many forms and can be used for many different teams and purposes. Documentation displays and describes what a product is, how it works, and how to use it properly.
Here are some examples of what documentation can include:
- Product information
- Quickstart guides
- Installation instructions
- Administration guidelines
- Frequently asked questions (FAQs)
- Release notes
Learn more: What is documentation?
Why is documentation important?
Technical documentation plays an important role in the overall customer experience and can influence purchase decisions, renewal rates and customer satisfaction. This is only set to increase with the millennial customer coming of age. According to an SDL survey, 41% of millennials search for online tutorials, 33% search for technical documents and manuals, and 72% say that product information affects how they perceive a product. That makes it even more important to focus on your documentation now and into the future.
Why should you use Confluence for documentation?
Confluence is extremely collaborative. Couple this with the fact that it's a web app and you've got a platform built for teamwork - no matter where colleagues are in the world. This improves company collaboration and makes quicker, more accurate document management possible.
Confluence's simplicity makes it ideal for creating documentation for users of all experience levels—and that’s before you start using Confluence macros. If you're already familiar with Atlassian tools like Jira, Confluence is a natural choice for documentation.
Using Confluence for documentation: 6 steps to success
Step 1: Create a new space for your documentation
To lay out the framework for your new documentation, you’ll need a space for it to live. Then, you’ll need to create and manage pages for your documentation.
To create a Confluence space, select Spaces > Create space. Then choose the Documentation space template (or create a Blank space to start from scratch).
From here, you can name your space, choose an icon, and set permissions.
Step 2: Create and manage Confluence pages
If you’re familiar with Confluence, you should know how to create a new Confluence page. From your documentation space, select + Create > Page, then start adding your content.
If you've got pages in other spaces that you need to move over into your documentation space, check out our guide on how to move Confluence pages.
What are the best practices for managing Confluence pages?
- Turn on restrictions during page creation: Unfinished documentation looks unprofessional and might even give users the wrong information. We recommend restricting page permissions to only those who need access until the pages are ready. When you share pages with reviewers for their feedback, don’t forget to give them access!
- Use comments to improve documentation: Inline comments can be extremely useful during the documentation drafting process. Just make sure to delete any comments before publishing your page.
- Use an app to improve Confluence document management: Navigating Confluence pages can be difficult. Guided Pathways for Confluence lets you turn documents into branching guides, helping users find the right answer quicker.
Step 3: Make your content more engaging
It may be technical documentation, it doesn't need to be dull or text-heavy. In fact, good documentation should feature plenty of images to help show users what they need to do. Use up-to-date screenshots, gifs, and video walkthroughs alongside text to annotate the key features and steps.
In addition to images, your documentation should be eye-catching, professional, and easy to read. This means using subheadings, bold text, and sections appropriately. Many companies design their documentation to match their website and overall brand identity.
A visual documentation homepage created with Content Formatting Macros for Confluence
⎯⎯
🔧 There's an app to help with that!
Content Formatting Macros for Confluence lets you customise your pages and content to boost user engagement. Add buttons to draw attention, make links interactive, and design cards to display key information—plus much more!
Step 4: Make your pages clear and easy to navigate
Part of making your pages pretty is keeping them clear of clutter and breaking up chunks of text into easily digestible sections.
The Tabs macro (part of Content Formatting Macros for Confluence) is tailor-made for sectioning off text, which keeps your pages clean and tidy. When you've got large chunks of information, use tabs to split your content into relevant sections. This lets your users digest it at their own pace.
FAQ tabs created using Content Formatting Macros for Confluence
Once you've perfected your pages, it's time to focus on your Confluence site structure and navigation. You'll want to avoid orphaned pages and make sure there are prominent links between relevant sections.
⎯⎯
🔧 There's an app to help with that!
Guided Pathways for Confluence is perfect for creating smoother user journeys through your documentation.
The app lets you organise your Confluence pages into branching, step-by-step guides, making your documentation more structured and user-friendly. You can also easily edit and hide outdated guides to keep your documentation up-to-date and relevant.
Step 5: Get your Confluence documentation online
Time to take your space documentation public? You’ll need to use an add-on like Scroll Viewport to publish directly to the web, adding a customised web layer on top of the Confluence documentation. This means end users can view your Confluence documentation as a stylised website - without compromising your internal Confluence user interface.
Step 6: Seek out user feedback
Any UX designer knows that a good website is one that users want to interact and engage with, and your documentation should be no different. It’s important to give users the chance to share their feedback.
⎯⎯
🔧 There's an app to help with that!
With Forms for Confluence, you can embed surveys and polls to let users quickly rate and review content while they're still on the page.
Whether it’s a simple star rating or a comment box, you'll get useful insights that can help make your documentation better than ever.
Create better Confluence documentation with our apps
Whether you want to make more engaging pages, improve user navigation, or gather user feedback, we've got the app to help you do it.
Related Content
Read more
Written by
Holly Aspinall
Content Marketing Manager
As an experienced Content Marketing Manager, Holly is dedicated to writing valuable, accessible guides that help users understand their tools better and get more out of their workday.
LinkedIn →
LinkedIn →
Related Content
Read more