Confluence for documentation

[Peter]

Our team relies heavily on Confluence for documentation, but most pages feel dry and unengaging.

We want to make our pages more visually appealing so that team members actually use them instead of asking the same questions over and over again.

How can we improve this?

[Kristian Klima · Accepted solution]

Hi @Peter 

You have almost too many options :) 

• explore built-in Confluence macros - info boxes, expand macro, screenshots...
• look at 'skins' also known as theme apps - some are oriented more towards intranet users (Aura, Mantra...) some gear towards documentation (Spacecraft, Refined).
• Full fledged documentation portal apps - such as Instant Website or Scroll Viewport. Viewport, for example, is not just for visuals, it can massively expand your docs options (with the help of other Scroll apps) - versioning, conditional content variants, localization, you can choose which sections of a space you wanna turn into documentation etc.

For example, this our Documentation Center built in Scroll Viewport:  https://docs.emplifi.io/

You choice will also depend on other requirements. 

• Do you want your documentation to be on your own domain?
• Do you want anonymous users to access your documentation? And if so, does your policy allow making Confluence spaces open to anonymous access? 
• Another thing to consider - do you want BOTH the public portal and the customers-only portal? For example, Viewport and Instant Websites both support controlling access to your documentation with your SSO. In other words, your docs will remain private, customers-only, without the need to give your customers paid Confluence seats.

I'm not linking to the marketplace apps because it'd be too many links here.

[Fadoua · Accepted solution]

Hi @Peter 

Welcome to the Atlassian Community!

There are couple of videos on YouTube to help users design some appealing Confluence pages.

https://www.youtube.com/results?search_query=Create+appealing+Confluence+pages+

Let me know if you have any questions.

Best of luck!

Fadoua

[Laurie Sciutti · Accepted solution]

Hi @Peter and welcome to the Community!  In addition to the information provided by the other responses here, I definitely recommend incorporating labels and "index" pages which utilize Content by Label macros to help organize space pages / info.  Definitely helps to cut down on the "noise".  I've also found that you reorder pages and move them out of navigation view and as long as you have those index pages, users can still access that content easily.  We also use an add-on Brikit Theme Press which allows you to really get into the weeds and design your spaces for more engaging content.  Doesn't look like it's available for Cloud but you can find others in the Marketplace.  And don't forget about the pre-done templates ~ those help as well.  Good luck!

[Sahir Maharaj · Accepted solution]

Hi @Peter

Great question. I’ve seen Confluence turn into an information black hole if it’s not structured properly.

What worked for me was setting up a clear hierarchy based on how teams actually work. I created separate spaces for different departments (like Engineering, Product,etc…) and then used consistent page structures within each space (I usually start with broad topics and drilling down into specifics)

Also, I recommend you to explore using templates. Its super useful to ensures that every page follows a standard format, making it easier to navigate. @Kristian Klima and @Fadoua have shared some excellent resources :)

I also use the Page Tree macro to create dynamic navigation so people don’t have to dig through unrelated pages.

Finally, my team set up quarterly content reviews, where we check and update key documents to keep everything relevant.

When Confluence is structured right, it becomes an asset instead of a headache.

Currently for us, it makes it so easy for new team members to onboard and for existing teams to find what they need without wasting time.

Let me know if you have any questions!

[Zoriana Bogutska_Adaptavist_]

Hi @Peter 

To the list of solutions mentioned before, you can: 

• Check this article https://community.atlassian.com/forums/App-Central-articles/How-to-create-documentation-in-Confluence-6-step-guide/ba-p/2375291 
• Consider the Mosaic app, which includes professionally looking full-page templates for the most popular Confluence use cases, including documentation. 

Here are example pages that represent templates Mosaic provides

Mosaic was created by my team, so let me know if you have any questions about it. I'm happy to help! :)

[Elena Zanchetta_Communardo]

Hi @Peter Great question! Making Confluence pages more engaging can really boost adoption and reduce repeat questions. I recently wrote an article on this exact topic, covering best practices to make documentation more user-friendly. Check it out here: Optimizing Confluence Docs: Ensure Users Find What They Need. Hope it helps!

[Yulia Lenina _AppFox_]

Hi @Peter and welcome to the Community!

In addition to the comments above, I would also suggest looking at your Confluence Knowledge Hub from a bird’s-eye perspective - how it is organised overall, not just in terms of engagement. There may be other reasons why people are not using it the way you want.

One of the biggest challenges is often an organizational one - you may need to train people not only on how to use Confluence but also on how to manage and work with information effectively in general.

Based on best practices from our and our customers experience, I’d give general "technical" recommendations:

1. Using Separate Spaces : Create a dedicated Confluence space just for your customer knowledge base. This ensures customers don’t have access to internal or sensitive information.
2. Setting Permissions Carefully: Use Confluence’s permission settings to control access so customers only see what’s intended for them.
3. Structuring Content for Easy Navigation: Organise pages using a clear hierarchy (FAQs, user guides, troubleshooting, etc.), and use labels/metadata to improve searchability.
4. Managing Content with Workflows for Confluence – our app can help automate content approval and ensure only reviewed and up-to-date documents are published. You can:
   • Set up approval workflows before content goes live.
   • Automatically publish approved documents from an internal space to the customer knowledge base.
   • Track document status to ensure outdated information is reviewed and updated.
   • And much more
5. Publishing with Scroll Viewport: If you want a more polished, website-like experience, Scroll Viewport by K15t can turn your Confluence space into a professional customer portal.

Also, those articles may be helpful: 

https://community.atlassian.com/t5/App-Central-articles/%EF%B8%8F-Building-a-Knowledge-Base-Step-by-Step/ba-p/2869875

https://community.atlassian.com/t5/App-Central-articles/How-to-create-a-knowledge-base-in-Confluence/ba-p/2291458

https://community.atlassian.com/forums/App-Central-articles/Building-a-Knowledge-Hub-Like-a-Michelin-Star-Restaurant/ba-p/2965261