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.
|Quick guide to creating a knowledge base space|
The rest of this page gives more details of the above procedure.
Below is a quick guide to adding a space. See Setting up a New Global Space for a full description.
The homepage of your new space will appear. Because you created the space, you are the space administrator. Now you can do some basic configuration, as described in the sections below.
Define the space permissions to determine who can do what in your new space.
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.
- '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' 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 (Bill) maintains full Space Administration rights.
For detailed information, see the documentation on:
When you created your space, Confluence created a homepage with default content and a default title, 'Home'. You will want to change the title and content.
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 in our product documentation.
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:
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 reusable content throughout your knowledge base space.
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'.
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.
Here are some examples in our documentation:
Create the table of contents for your knowledge base, by adding the top-level pages for all the usual sections. For instance, 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
Now do the same for all the sections of your Knowledge Base that you wish to appear in the left-navigation bar of the Documentation theme. Below is what the Table of Contents looks like for our Confluence Knowedge Base:
Let's populate the knowledge base homepage with content by creating an RSS feed that your coworkers and customers can subscribe to and receive important updates on 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 and turn your knowledge base from reactive to proactive:
Congratulations! You have successfully created a proactive knowledge base.
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.
You can now monitor the activity and traffic for every page you create in your Confluence instance and Knowledge Base.
Hint: If 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.
Read David Simpson's blog post about Tracking Confluence Usage with Google Analytics for more information.
Now that you can monitor the traffic and activity of your knowledge base, let's measure its effectiveness. When the Content Survey and Reporting Plugin 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 info complete?" or "Was the article well-written?".
- Rollup at-a-glance view of the metrics for the whole space
Lastly, the Content Survey and Reporting Plugin 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 Plugin.
This plugin only functions properly if the Documentation Theme is applied to the space.
Let's install the Content Survey and Reporting Plugin using Confluence's Universal Plugin Manager.
Now that you've installed the Content Survey and Reporting Plugin, let's configure a survey:
Now that you've added a primary question, let's test out the plugin by adding it to the footer of the Documentation theme so that every page within your Knowledge Base space includes your survey.
With the Content Survey and Reporting Plugin you can dramatically improve the quality of our 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 Plugin in the Confluence Knowledge Base:
Survey results are viewable by Space Administrators only. The plugin develops three results:
- Pages with Results - Determine page-by-page, which are you most effective knowledge base articles and which ones need improvement.
As you can see, the plugin 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 Plugin 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.
As mentioned, the Content Survey and Reporting Plugin 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 plugin 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 Plugin 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.
If a user doesn't choose one of the recommendations from the quick search drop-down menu, the plugin will display a search results page inside the Knowledge Base space rather than directing them to the Confluence global search page. By keeping the visitor in the same space, it will help new users find the information they need and only navigate to pages they intend to, minimising confusion and the number of times a user has to hit the 'Back' button in their browser.
See Confluence Content Survey and Reporting Plugin for a full description in the plguin's documentation.