Documentation for Confluence 5.4.
Documentation for Confluence OnDemand and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

This guide is for people who want to develop and publish a knowledge base using Confluence. You'll find Confluence useful because it combines professional web publishing features with the ease-of-use and flexibility of a wiki - requiring a low barrier to entry, but high quality output for all your team members. Confluence provides all of the collaborative features for your reports (such as automatic versioning, granular enterprise security, email and RSS subscriptions, and JIRA integration). This page is a quick-start guide to creating a wiki space for a knowledge base.

Step 1. Add a space and select the Documentation theme

Below is a quick guide to adding a space. See Setting up a New Global Space for a full description.

  1. Go to the Confluence dashboard and choose Create Space > Blank Space.
    Hint: If you cannot see Create Space, this means that you do not have permission to add spaces. Please contact your Confluence administrator.
  2. Choose Next then enter a space name and a short, unique space key.
  3. Leave the permission settings as default, or choose to allow only yourself to view or contribute content to this space. You can change these settings later and with more flexible options.
  4. Choose Create.
  5. Your new space appears. Choose Space Tools in the sidebar.
  6. Choose Look and Feel > Themes and select the Documentation theme.
  7. Choose OK.

The home page of your new space will appear, and your space will be using the Documentation theme. Because you created the space, you are the space administrator. Now you can do some basic configuration, as described in the sections below. From this point on, instructions will refer to navigating in the Documentation theme, which is slightly different to the default theme.

Step 2. Set the space permissions

Define the space permissions to determine who can do what in your new space:

  1. Choose Browse > Space Admin at the top of the screen.
    Note: The 'Space Admin' option appears only if you are a space administrator for the space or you are a super user (a member of the confluence-administrators group).
  2. Choose Permissions.
  3. Choose Edit Permissions.
  4. Set the permissions to suit your needs then choose Save All.
    • You can add groups and/or individual users to the list, then select the permissions for each group or user.
    • You can also set the permissions for anonymous users – these are people who have not logged in to the wiki. Anonymous access is available only if enabled for the entire Confluence site. We recommend this setting if you are using this space for Technical Documentation or for a Knowledge Base.
    • Note that you can change these permissions at any time. You may want to restrict the permissions to specific groups now, and later open the space to more people.

More about permissions

Confluence has a robust and granular permissions scheme that you can use to determine who can view, comment on and even update the documentation. There are three levels of permissions in Confluence:

  • Global permissions apply across the entire site.
  • Space permissions apply to a space.
  • Page restrictions allow you to restrict the editing and/or viewing of a specific page. Below we discuss a way of using these in the draft, review and publishing workflow.

Space permissions in Confluence are simple yet granular enough to be useful for technical documentation. You can:

  • Use the permission levels to control who can create pages in the space, delete pages, create comments, delete comments, administer the space, and so on.
  • Grant a permission level to one or more users, and/or to one or more groups, and/or to anonymous users.

Terminology:

  • 'Anonymous' means people who have not logged in to the wiki. These are users that won't affect your the number permitted by your license.
  • The 'confluence-users' or 'users' group is the default group into which all new users are assigned. Everyone who can log in to Confluence is a member of this group.

For example, you might allow 'Anonymous' users specific view and content creation rights so that they can access and engage with your knowledge base while your team lead (Rach) maintains full Space Administration rights.

Screenshot: Allowing anonymous users to add specific content

For detailed information, see the documentation on:

Step 3. Customise the title and content of the home page

When you created your space, Confluence created a home page with default content and a default title. You will want to change the title and content.

  1. Go back to your space home page, by choosing the space name in the breadcrumbs at the top of the screen.
  2. The space home page appears. By default, the page title is 'X Home', where 'X' is the name you gave your space.
  3. Choose Edit.
  4. Change the title to suit your needs.
  5. Update the content to suit your needs.
    Hint: If you do not know what to add yet, just add a short description. You can refine the content of the page later. Take a look at an example of a homepage.
  6. Choose Save.

Step 4. Customise the Documentation theme

When you added this space you chose the Documentation theme, which provides a left-hand navigation bar and a good look and feel for a knowledge base. If necessary, you can configure the Documentation theme to add your own page header and footer, or to customise the default left-hand navigation bar. These customisations affect the online look and feel of your knowledge base. See Configuring the Documentation Theme for the full description.

  1. Choose Browse > Space Admin (if you have not yet selected the documentation theme choose Space Tools > Look and Feel).
  2. Choose Themes.
  3. If the space is not yet using the Documentation theme, apply the theme now.
  4. Choose Configure theme.



  5. The 'Documentation Theme Configuration' screen appears. Customise the left-hand navigation bar, header and footer to suit your needs. Details are in the documentation. Here are some hints:
    • The Page Tree check box determines whether your space will display the default search box and table of contents (page tree) in the left-hand panel.
    • The Limit search results to the current space check box determines whether Confluence will search only the current space or the whole Confluence site. This setting affects the default search. Viewers can override it each time they do a search.
    • Enter text, images, macros and other wiki markup into any or all of the three text boxes for the the left-hand navigation bar, header and footer. You can use the Include macro and the Excerpt Include macro to include re-usable content.
    • Any content you add to the navigation panel will appear above the default page tree.
    • If you like, you can remove the default page tree (by unticking the box) and add your own, customised version of the Pagetree macro instead.
  6. Choose Save.

Example of a customised footer

Take a look at the footer of a page in the Crowd documentation space.

To produce the above footer, we have the following content in the footer panel in the Documentation theme configuration screen:

Here it is in text form:

{include:_Documentation Footer|nopanel=true}
{include:ALLDOC:_Copyright Notice|nopanel=true}

The above content consists of two Include macros.

  • The first macro includes a page called _Documentation Footer. This page contains the big blue buttons and hyperlinked text.
  • The second macro includes a page from a different space, the ALLDOC space, called _Copyright Notice. This page includes our standard copyright notice, used in all our documentation spaces.
  • In each include macro, the content has been drawn from an inclusions library, a hidden content repository, from which you can store frequently and re-usable content throughout your knowledge base space.

Step 5. Create an inclusions library to manage reusable content

Using Confluence, you can dynamically include content from one page into another page. You can include a whole page into another one, using the Include macro. You can also define an ‘excerpt’ on a page, and then include that excerpted text into another page using the Excerpt Include macro.

To organise your re-usable content, we recommend that you create a set of pages called an 'inclusions library':

  1. Choose Create and create a new page in your space.
  2. Enter a suitable title. We use '_InclusionsLibrary'. The unusual format of the title helps to let people know this page is special.
  3. Enter some content and save the page. We enter text explaining the purpose of the inclusions library and how to re-use the content. You can copy our text by clicking through to one of the example pages listed below.
  4. Choose Browse > Pages and drag your new page above the space homepage. 
  5. Go to your new inclusions page and choose Create to add child pages containing your re-usable content. See the examples of our own inclusions libraries listed in the examples below.


Some notes about inclusions libraries:

  • The inclusions library is not a specific feature of Confluence. The pages in the inclusions library are just like any other Confluence page.
  • The pages are located at the root of the wiki space, not under the homepage. This means that they will not appear in the table of contents on the left and they will not be picked up by the search in the left-hand navigation bar either.
  • The pages will be picked up by other global searches, because they are just normal wiki pages.
  • We have decided to start the page name with an underscore. For example, '_InclusionLibrary'. This indicates that the page is slightly unusual, and will help prevent people from changing the page name or updating the content without realising that the content is re-used in various pages.

Examples of inclusions libraries

Here are some examples in our documentation:

Step 6. Create the table of contents

Create the table of contents for your knowledge base, by adding the top-level pages for all the usual sections. For example, our technical support team designed the following pages in the Confluence Knowledge Base on our public wiki:

  • Browse Articles by Label
  • Browse Articles by Top Ranked Content
  • Browse Articles by Page Tree Hierarchy
  • Browse Articles by Version
  • Subscribe to Proactive Announcements

To start your table of contents:

  1. Go back to your space home page, by clicking the space name in the breadcrumbs at the top of the screen.
  2. Choose Create to add the page as a child of the home page.
  3. Enter the page title. For example: 'Browse Articles by Label'.
  4. Enter the content of the page.
    • Hint: If you do not know what to add yet, just add a short description then refine the content of the page later. If you like, you can follow an outline similar to the Confluence Knowledge Base and add the Label List macro. This displays a hyperlinked alphabetical index of all labels within the current space. As you create content in this space and apply appropriate labels, the macro will update this page automatically.
  5. Choose Save.

Now do the same for all the sections of your knowledge base that you wish to appear in the left-hand navigation bar of the Documentation theme. Below is what the table of contents looks like for our Confluence Knowledge Base:

Step 7. Give people an RSS feed they can subscribe to

Let's populate the knowledge base home page with content by creating an RSS feed that your co-workers and customers can subscribe to, so they an receive important updates from your knowledge base and technical alerts on your products.

This is a strategy that Atlassian's technical support team uses to create a proactive knowledge base that provides technical alerts to customers and coworkers and helps solve support issues before they're even created.

By following the quick guide below, you'll create a homepage similar to the one Atlassian's technical support team has created for the Confluence Knowledge Base on our public wiki:

Creating your RSS feed:

Confluence can filter spaces by content type. To filter your knowledge base for 'blog post' content, do the following:

  1. Go to a page in the space and choose Blog in the sidebar.
    Or, if you are using the Documentation theme, choose Browse > Blog at the top of the screen.
  2. Copy this URL to your clipboard.
  3. Create an RSS feed for the URL of your knowledge base space.
    Now your RSS feed will consist of any blog posts created in the knowledge base space.

Highlighting your technical announcement RSS feed

  1. Go to your space home page.
  2. Choose Edit.
  3. Insert an 'h2' heading, such as 'Important Technical Announcements'.
  4. Insert bold text that reads something like, 'Copy the RSS feed into your favourite RSS reader:'.
  5. Choose Insert > Other Macros to open the Macro Browser.
  6. Select the 'Panel' macro in the Macro Browser and specify your desired macro preferences. We recommend that you change the Panel Title, Border Style, and Background Color to further highlight the panel on the page.
  7. Choose Insert.

Inserting a Blog Posts macro

  1. Inside the Panel macro placeholder choose Insert > Other Macros to open the Macro Browser again.
  2. Select the Blog Posts macro in the Macro Browser and specify the following preferences:

    • Content Type to Display: Title
    • Restict to These Spaces: Your knowledge base Spacekey
    • Maximum Number of News Items: 5
    • Sort By: Creation
    • Reverse Sort: Tick the box
  3. Choose Insert to insert the Blog Posts macro onto the page inside your Panel macro.
    Now your panel will display the last 5 blog posts created in your knowledge base space.

Inserting your RSS feed into your 'Technical Announcements' panel

First, let's create a link so that your coworkers and customers can view all of the blog posts in your knowledge base space. See Working with Links for a full description in our product documentation.

  1. Place your cursor after/below the Blog Posts macro in the Panel macro placeholder.
  2. Type: 'View more recent blog posts'.
  3. Highlight this text and click Link on the editor toolbar.
  4. Select 'Web Link' and paste the link you copied to create your RSS Feed.
  5. Choose Insert.

Now, let's insert your RSS Feed into your panel by linking an image. See Linking an Image for a full description in our product documentation.

  1. Attach an RSS Icon  to the page by dragging and dropping it into the editor (preferably below the link you just created). See Drag-and-Drop for a full description in our product documentation.
  2. Choose the RSS Icon image and choose the 'Align right' button on the editor toolbar.
  3. Choose Border in the image properties panel.
  4. Link the RSS Icon by selecting the image and then choosing Link on the editor toolbar.
  5. Choose the 'Web Link' tab and insert the RSS Feed URL you created.
  6. Choose Insert to link your RSS Feed to the RSS Icon image.
  7. Choose Save to save your page and test your RSS Icon.

Congratulations! You have successfully created a proactive knowledge base.

Step 8. Set up Atlassian's Content Survey and Reporting add-on

(warning) The information in this step does not apply to Confluence OnDemand.

 

Now that you can monitor the traffic and activity of your knowledge base, let's measure its effectiveness. When the Content Survey and Reporting add-on is activated for a space, it will generate a report that includes:

  • Direct feedback from customers about article quality
  • Amalgamated 'composite score' results
  • Answers to secondary questions, such as 'Was the information complete?' or 'Was the article well-written?'.
  • A rollup at-a-glance view of the metrics for the whole space.

Lastly, the Content Survey and Reporting add-on will institute 'intelligent searching' which means that, based on the results of the surveys, higher ranked pages are promoted in search results, so your best and most popular pages are found easiest. This is a quick guide for how to set up the Content Survey and Reporting add-on.

(info) This add-on only functions properly if the Documentation theme is applied to the space.
Let's install the Content Survey and Reporting add-on using Confluence's Universal Plugin Manager:

  1. Log into Confluence as a System Administrator or Confluence Administrator.
  2. Choose the cog icon  at top right of the screen, then choose Confluence Admin.
  3. Choose Manage Add-ons.
  4. Search for the 'Content Survey and Reporting add-on'.
  5. Choose Install.

You can also go to the Atlassian Marketplace and download the add-on and install it directly.

Now that you've installed the Content Survey and Reporting add-on, let's configure a survey:

  1. Go to your space.
  2. Choose Browse > Space Admin at the top of the screen.
    Note: The 'Space Admin' option appears only if you are a space administrator for the space or you are a super user (a member of the confluence-administrators group).
  3. Click Configure Survey under 'Knowledge Base Survey'. Here you can:
    • Add a question
    • Edit a question's text
    • Activate or deactivate a question
    • Edit the response text
  4. Configure a 'Primary Question' for the survey



  5. Choose Save.

Now that you've added a primary question, let's test out the add-on by adding it to the footer of the Documentation theme so that every page within your knowledge base space includes your survey:

  1. Choose Browse > Space Admin at the top of the screen.
    Note: The 'Space Admin' option appears only if you are a space administrator for the space or you are a super user (a member of the confluence-administrators group).
  2. Choose Themes.
  3. Choose Configure theme.
  4. Go to the 'Footer' section of the 'Documentation Theme Configuration' page and insert this recommended markup to achieve a nice layout of the Content Survey and Reporting add-on:
     

  5. Choose Save and go to your space homepage to view your Content Survey and Reporting add-on in the footer of the page.

With the Content Survey and Reporting add-on you can dramatically improve the quality of your knowledge base and the efficiency with which your team creates and maintains it. Here is an example of how our technical support team uses the Content Survey and Reporting add-on in the Confluence Knowledge Base:
 

Results displayed by the Content Survey and Reporting add-on

Survey results are viewable by space administrators only. The add-on develops three results:

  • Pages with results - Determine page-by-page, which are your most effective knowledge base articles and which ones need improvement.

    As you can see, the add-on develops a 'Composite Score' which ranks articles in search, so your highest scoring (best) content can be found most easily. The score is based on the last 32 votes cast, using the global search configuration. See Confluence Content Survey and Reporting Add-on for a full description on how Global Search boosting works.
  • Pages without Results - These are the pages in you knowledge base without survey results.
  • Rollup Report - This is the summary of all survey results. The report can be used to determine how effective your overall knowledge base content is.



Searching multiple spaces from your knowledge base

As mentioned, the Content Survey and Reporting add-on generates a composite score that ranks pages and articles within your knowledge base to make the highest (most well regarded) pages more retrievable by visitors. The add-on also improves Confluence search by allowing users to search multiple spaces without ever leaving your knowledge base space. This is really helpful for users that are unfamiliar with Confluence because they can keep the knowledge base as a point of reference within the greater instance of Confluence.

At Atlassian, our product knowledge bases and product documentation exist in the same Confluence instance so that we can make both available to 'Anonymous' users. Our Technical Support team uses the Content Survey and Reporting add-on to allow visiting users to search for Confluence resources in the product documentation space from the Confluence Knowledge Base space. This provides the visitor twice the chances of finding an answer to their question.

In the image below, you can see the space specific search used in the left-navigation bar to find content related to Confluence in both the 'Documentation' and 'Knowledge Base' spaces. Pages in the 'Documentation' space are listed first and pages in the 'Knowledge Base' space are listed second.

Step 9. Insert Google Analytics code into Confluence's custom HTML

(warning) The information in this step does not apply to Confluence OnDemand.

Now that you have a strong foundation for a knowledge base, it's critical to assess how effectively it services your customers. Google Analytics is a tool that gives you rich insights into your website traffic and marketing effectiveness. You are going to want to understand how your customers are accessing the resources in your knowledge base. This is a quick guide to inserting Google Analytics HTML code into Confluence so you can measure your knowledge base traffic.

  1. If you don't have one already, create a Google Account and then create a Google Analytics Account using your Confluence instance's URL.
  2. Copy the Google Analytics code to your clipboard.
  3. Log into Confluence as a System Administrator or Confluence Administrator.
  4. Choose the cog icon  at top right of the screen, then choose Confluence Admin.
  5. Choose Custom HTML under 'Look and Feel'.
  6. Choose Edit to insert custom HTML into your Confluence instance.



  7. Paste your Analytics code you have saved to your clipboard into the table labeled At end of the BODY.
  8. Choose Save.

You can now monitor the activity and traffic for every page you create in your Confluence instance and Knowledge Base.
HintIf your knowledge base only represents a space within your greater Confluence instance, you can search Google Analytics for activity in the specific space by exclusively filtering for the space key.

(info) Read David Simpson's blog post about Tracking Confluence Usage with Google Analytics for more information.

Note about add-on support

Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on add-on support.

Next Steps

See Using Templates and Formatting Macros in a Knowledge Base for next steps.

  • No labels

8 Comments

  1. Create Articles by Top Ranked Content uses the kbtoparticles macro, which is part of the Content Survey and Reporting Plugin. Is a 4.0 update in the works?

  2. "Configuring a Survey

    1. Go to your space homepage by clicking the appropriate breadcrumb in the top-left of your screen.
    2. Choose Browse > Space Admin.
    3. Click Configure Survey under 'Knowledge Base Survey'. Here you can:
      • Add a question
      • Edit a question's text
      • Activate or deactivate a question
      • Edit the response text
    4. Configure a 'Primary Question' for the survey"

    I can't seem to find this option anymore in my 4.3 Enterprise WIKI. It seems to have disappeared. Help?

  3. Anonymous

    Same Problem....

    "Configuring a Survey

    1. Go to your space homepage by clicking the appropriate breadcrumb in the top-left of your screen.
    2. Choose Browse > Space Admin.
    3. Click Configure Survey under 'Knowledge Base Survey'. Here you can:
      • Add a question
      • Edit a question's text
      • Activate or deactivate a question
      • Edit the response text
    4. Configure a 'Primary Question' for the survey"

    I can't seem to find this option anymore in my 4.3 Enterprise WIKI. It seems to have disappeared. Help?

  4. How do I edit the footer? The directions above say:

    Choose Configure theme in the yellow area of the 'Current Theme' section at the top of the page.

    I can find no such thing in Confluence 5.0.

    EDIT: I found it. There is no yellow area, it's just below the description of the theme.

    1. Hi Steven, 

      Thanks for posting your question (and answer). Seems I missed that Confluence 4.3 reference when updating the docs for Confluence 5's new interface. I've now corrected that step.  Thanks for pointing it out (smile).

      Rachel

  5. this page seems a bit outdated for confluence 5.3? it does not mention the special sort of space (how to create a new one or how to convert an existing one into the new knowledge base space). the content and survey plugin is also not available for 5.3

    1. Hi Werner, you are correct, the Knowledge Base space blueprint was released with Confluence 5.3.  I will be revising / retiring these special uses of Confluence guides very shortly - most likely with Confluence 5.4. 

      In terms of converting an existing space into a Knowledge Base base - there is no way to retrospectively apply a space blueprint to a space, but in the case of the Knowledge Base space blueprint, you can make use of all its features in an existing space, for example:

      • The How-To and Troubleshooting article blueprints are available in all spaces (unless you choose to disable them) - you can edit the templates of these page blueprints too if you want to match your current content layout. 
      • The new Livesearch macro from the Knowledge Base space homepage can be added to any page.
      • The Browse by topic and Recently Updated macros from the homepage can be added to any page.

      Hope you enjoy trying out the new Knowledge Base space blueprint. 

      Rachel

       

  6. I have some questions regarding adding the survey to pages.

    If I follow your instructions to add the survey to the page footer of the theme I do not get the same results as you have achieved in the knowledge base pages linked to as examples.

    • The survey is not in a nice neat box and there is no colour - do I have to play with the css to get a similar effect? If so can you provide the code for that?  By looking at the page source I can now see that the survey is in a panel.
    • The survey displays below the comments section (where it is easy to miss). It that because the example pages do not use the theme footer, but instead they use an included page that must be added to each page manually?
      • If I use an included page, then I cannot seem to get the Dynamic Content by Label macro to display anything (it does not appear to be using the labels of the page that it is included in)

    Note: I am using confluence 4.3