Every member of your team has a lot of valuable information, whether it’s recorded or not. But in order to make the most of that value, it’s important to document it.
In this blog we’ll address 4 of the main best practices for creating powerful documentation that helps teams work better together and breaks down silos and roadblocks — including tips for how you can use specific Confluence features to meet those best practices.
New to Confluence? Check out our beginner’s resources, What is Confluence Used For? and The Ultimate Confluence Guide >>
Why is Good Documentation Important?
Good documentation allows people to find the information they need quickly and easily, and helps ensure consistency throughout your team and organization. It also helps new team members get onboarded quickly and cross-functional teams communicate more effectively.
With good documentation, you’ll see increased organizational efficiency and streamlined collaboration, so teams can focus on innovating and problem solving rather than getting caught up in information silos or struggling to find what they need.
These benefits are applicable to teams and organizations of all types, but are especially important when technical information is involved. For example, software documentation is a crucial resource for software engineering teams — so crucial, in fact, that we wrote a whole ebook about how to get it right!
If you’re interested in learning more about the importance of documentation for effective teams, check out our blog on the benefits of Confluence documentation for all types of teams.
Back to topUsing Confluence for Documentation: 4 Best Practices to Follow
So you’re ready to build new documentation or overhaul your existing documentation — but this can be a daunting task for a team or organization that has a lot of knowledge to record. Where do you start?
Here are 4 ways that you can ensure your Confluence documentation is providing value to your team along with Confluence-specific tips to help you achieve each goal.
Step 1: Make It Organized
Before you start building out documentation, consider if you should create a dedicated Confluence Space for it.
If you’re building documentation for an entire product or marketing team, for example, you may want to create a team space that can house those documents. But if you have a team space already and are looking to document something on a smaller scale like a short project, you probably don’t need to create a separate space for that.
Having a dedicated space for your team, or possibly even for major organizational initiatives, will help you organize your documentation more easily as you add more content to it.
Pages within a space should also be well-organized so people know exactly where to go to find what they need. Documentation should be a helpful resource — not a frustrating one. As you build out your documentation, consider the page hierarchy and which pages can be nested under others for clearer organization.
Confluence Tip: Labels
Labels organize Confluence pages and attachments by category. If you label your Confluence pages with important keywords, it’s easy to search for relevant information.
Not only is this helpful when searching for resources, it’s also helpful when the time comes to update your documentation. You can search for everything under a label to make sure you don’t miss any places where information should be updated.
It’s easy to add labels to a page, and you can do it in both viewing and editing mode. Confluence Support’s page on using labels will guide you through all the steps you’ll need to know.
Step 2: Make It Clear
Documentation should always be as clear and concise as possible. Give people the context they need, but don’t overwhelm them with unnecessary details that slow down the creative process or make it more difficult for them to find important information.
One way to make your documentation clear and concise is by curating content thoughtfully. What do your teammates need to see, and what isn’t necessary?
You can always use your Personal Space in Confluence to record thoughts and ideas that aren’t ready for the full team yet, then share those pages with others when the occasion arises.
But making content clear isn’t just about what you present, but also how you present it. Be sure to structure each page effectively, using headings and subheadings to break up long sections of text. It’s easier to read content that is broken up into manageable chunks.
Confluence Tip: Table of Contents
Your team should always know what to expect upon entering a page, and it should be easy for them to find the section they need. One way to help with this is by including a Table of Contents at the top of each page, which can be added easily using the Table of Contents Macro in Confluence.
Step 3: Make It Visual
Sometimes the most effective way to communicate information is through visuals rather than words. Visuals help people process information more quickly and also help with holding readers’ attention. In fact, more visually appealing Confluence pages tend to get more engagement on average.
Whenever there’s an opportunity to convey complex information through a visual that makes it easier to understand at a glance, be sure to take it. Whether that’s a chart or graph to visualize data, a relevant and helpful image, or a diagram that illustrates a process or structure, there are many ways to customize your documentation in a way that’s both visually appealing and helpful to your readers.
Want to learn more about creating visually appealing Confluence pages that will make your team excited to read? Visit our blog on creating engaging Confluence pages >>
Confluence Tip: Diagrams
If you’re on a team that follows complicated processes or workflows, or you work with complex structures like a network or database, diagrams are one of the most helpful resources you can include in documentation.
You can always upload images of diagrams you’ve created in other tools or use connector tools to add them in, but the quickest and easiest way to add diagrams to your documentation in Confluence is through a diagramming app like Gliffy that allows you to diagram directly within Confluence pages.
With Gliffy, there are no extra saves, logins, or imports. Plus, if you place the same diagram in multiple locations in your Confluence space, it will automatically update everywhere whenever the original is updated, so your team is always up to date.
If you already have Gliffy installed, all you need to do to add a diagram to a Confluence page is type “/gliffy” and select the Gliffy Diagram option. See our guide to creating diagrams in Confluence to learn more!
Step 4: Make It Consistent
It’s easier for people to find what they need and contribute to documentation themselves when necessary if team documentation has a consistent set of standards. For example, all event plans, or all strategic plans, should look similar and have similar information in similar sections.
Confluence offers a wide variety of templates that you can use to ensure consistency throughout your team’s space. Plus, templates also make it easier for beginners to contribute.
Confluence Tip: Custom Templates
Confluence Cloud Space administrators can create customized templates for other users in Space Settings. This is helpful when you want to standardize a type of page that Confluence doesn’t have a template for, or if you don’t like any of the options available.
But what if you don’t have admin permission? You can still create blank pages with placeholder text that can be copied and used as templates. If you do this, you might want to create a “Templates” label so they are all grouped together and easy to find.
Back to topStart Supercharging Your Documentation
Once your documentation is ready to publish — following all of these best practices, of course — make sure to set permissions appropriately so everyone who needs access to it has it. Then, make sure your team is aware of its availability as a resource.
Since Confluence is built for collaboration, make sure to take advantage of those features along with its strength as a knowledge base. You can make your Confluence documentation a hub for sharing and recording ideas for the whole team, rather than a one-way method of communication.
Get started in Confluence if you haven’t already, and then make sure to try Gliffy for all your visual documentation needs:
Want a few extra tips for making your documentation stand out? Check out our blog on the top 5 apps for your Confluence knowledge base!