Build a documentation site/knowledge base
- Philip Garrity
- Madzy Soetman
The terms documentation and knowledge base are often used interchangeably. For simplicity’s sake, we refer to this type of site as a knowledge base in this guide.
Note that knowledge bases built with Confluence and Refined provide one-way communication: users get information but can’t contact you. If you want to give users the opportunity to create support tickets, combine the power of Confluence and Jira on a help & support site.
Build a documentation site or knowledge base
If you’re reading this, you’re likely gearing up to take your Confluence knowledge base to the next level. There are many benefits to using Refined Sites for Confluence to transform your knowledge base into a highly customisable website, including easy-to-access information, intuitive navigation, improved user experience, and theming that matches your brand.
Step 1: Lay a foundation in Confluence
First things first: before you start building your knowledge base in Refined Sites, you’ll want to map out your content strategy. That means organising your content in Confluence so that the navigation is intuitive to users as they scour your Refined site for information.
We recommend to consider the following:
Prep your Confluence spaces. Confluence spaces serve as the building blocks of your knowledge base, so it’s important to align them with user needs. For example, if users look for information from different teams, every team should have a knowledge-focused space. While Confluence only lets you organise content into pages and spaces, Refined Sites adds another level of structure by letting you group together spaces into parent navigation items. More on that later, but you’ll want to ensure that your spaces in Confluence are compatible with your plans for your Refined site’s planned navigational and content structure.
Ensure that your spaces aren’t overcrowded. If a space contains a lot of pages and blogs and becomes hard to navigate, reconsider the purpose of the space and evaluate if it can be broken up into multiple dedicated spaces instead.
Set standards for formatting on Confluence pages, and don’t overload them with content. Macros from Refined Toolkit can help you organise content on-page to make it easy to digest.
Set Confluence space and page permissions to ensure that content is only available to the right user groups. Refined sites always respect permissions set in Confluence, to ensure that the content on your knowledge base is seen only by the intended users.
Step 2: Create your site and set permissions
With everything in order in Confluence, you can start building your Refined site:
Go to the Refined Administration > Sites and click the + button to create a new site.
Give the site a catchy name and subdomain. While you are welcome to keep this URL (formatted as example.refined.site), you can also set up a custom domain later. Changing the domain to knowledgebase.yoursite.com, for example, clearly communicates the site’s purpose and makes it easy to remember.
Head over to the Permissions tab to set your site access permissions. An internal knowledge base should be set to Private, so only logged-in users from your organisation can see it. If you want everyone to be able to access the knowledge base, set it to Public instead.
Step 3: Start building your knowledge base in Refined Sites
Go to the Site structure tab to add content to your site and organize it. The structure you establish here is automatically reflected in the site’s navigation menu.
Add content to your knowledge base
Click the + Add Content button:
When you add a Confluence space, you create a landing page on your site. Through this page, users can access the Confluence space’s pages and blogs. Landing pages are customisable — we’ll get into that later on in this guide.
A Refined Page is a customisable landing page. Although it is not connected to any specific Confluence content itself, you can use it to show content from the spaces that you group underneath it in the site structure. Any item that you nest below a Refined Page appears in a dropdown list in your site’s navigation menu.
Menu Folders also let you create dropdown lists in the navigation menu. As opposed to a Refined Page, a Menu Folder doesn’t have a landing page.
Links let you direct users to any page you want, on or off your site, straight from your site’s navigation menu.
Structure your knowledge base
Simply drag and drop items to arrange them into a hierarchy. Group items underneath Refined Pages and Menu folders to create dropdown lists in the site navigation menu. The key to a successful hierarchy is to think about the relationships between spaces and how they'll be used.
For example, you can create three menu folders which will be the main navigation menu items on your site: technical guides, product integrations and user resources. Everything you group underneath these folders in the site structure appears in drop-downs in the menu.
Menu folder | Can contain |
|---|---|
Technical guides | Spaces containing information about how to get started, administration, and security. |
Product integrations | Spaces used for documentation and collaboration. |
User resources | Spaces with information about company strategies, processes and goals. |
Step 4: Customise home and landing pages
You can customise your site’s homepage, as well as the landing pages for the Confluence spaces and Refined Pages that you added. You make them come to life in the Page Builder with the help of modules: your page’s building blocks. For example, highlight the latest news or use icons and buttons to direct users toward important pages.
Three tips for landing page success:
If you like the look of a page and want to apply that design on another page as well, simply reuse the page’s layout by exporting and importing it.
Need design inspiration? The Page Builder includes a range of templates, including ones for navigation and documentation. After applying the template, you can further adjust the page.
Personalise the user experience. For example, View Permissions let you decide who gets to see which content on the page - showing different users and user groups only what’s relevant to them. Set access to logged-in or non-logged-in users, limit access to certain user groups, or set no permissions at all for open access.
Step 5: Customise Confluence pages and blog posts
Use Space Settings to adapt your Confluence pages and blog posts to your site’s needs. For example:
On a public-facing knowledge base, you may want to hide the authors' profile pictures and names to keep them anonymous.
If you only have short knowledge base articles, you can disable the estimated read time for a cleaner look of the page. On the other hand, you can help users navigate long pages by adding a table of contents, which lists all headings on a page and moves with the user as they scroll down the page.
If your space contains a lot of pages, add a search bar to the space’s left-hand menu to help users find their way.
You have full control over the settings of each space: use global space settings to decide the default look of your spaces, and customise specific spaces with custom space settings (as shown below).
Step 6: Theme your site to match your brand
To apply your brand’s look and feel to your knowledge base, add logos and themes. If you have multiple sites (your Refined Sites subscription allows you to create as many as you like), you can apply different themes to each of your sites. This way, a knowledge base and an intranet can have different looks. You can also create themes for special occasions, for example to celebrate a new product release or company anniversary.
Step 7: Delegate admin permissions to key colleagues
How do you plan to maintain the site going forward? Is it a one-person job? Or are there other content creators who should have the ability to modify the structure, navigation, pages, themes, etc.?
If your answer is the latter, assign administrator permissions to key Confluence users in your organisation. Those users don’t have to be Confluence admins — they just need a Confluence account. You can delegate permissions on a per-site basis or for your entire Refined Sites instance.
Step 8: Add a cookie dialog
You have the option to enable a Cookie Dialog on your knowledge base, which can help users understand and consent to cookie collection. You can create a custom notification that complies with laws such as GDPR and CCPA, and with your organisation’s policies.
Step 9: Keep users informed
Communicate important information to your users by adding an announcement banner to the top of your Refined site. For example, a banner can inform users of a new release or scheduled maintenance.
What’s next?
For more inspiration, dive into our demo site and blogs:
And why not transform your Confluence and Jira instances into even more sites users love — you can create an unlimited amount of sites with your Refined Sites subscription:
We’re always happy to help if you have any questions: reach out to support.