This guide is for people who want to develop and publish technical documentation on Confluence. You will find it useful if you want to write a technical manual such as a user's guide, administrator's guide, installation guide, and so on. This page is a quick-start guide to creating a wiki space for technical documentation.
|Quick guide to creating a technical documentation 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.
- 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 technical documentation while your technical writing 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 the space you chose the Documentation theme, which provides a left-hand navigation bar and a good look and feel for technical documentation. 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 documentation. See Configuring the Documentation Theme for the full description.
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.
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 searches, because they are just normal wiki pages.
- We have decided to start the page name with an underscore. For example, '_My Page Name'. 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 documentation, by adding the top-level pages for all the usual sections:
- User's guide
- Administrator's guide
- Installation guide
- Configuration guide
- Release notes
- Whatever else you need
Now do the same for all the sections of your technical document. Here is an example of the Table of Contents for the technical documentation for Confluence 3.4:
If you are planning to provide PDF versions of your documentation, you may want to customise the PDF layout and styles for your space. You can skip this step for now and do it later, if you prefer. The instructions are in a separate section of this guide, dedicated to PDF. See Providing PDF Versions of your Technical Documentation.
Now that you have a strong foundation for a Technical Documentation space, 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 technical documentation. This is a quick guide to inserting Google Analytics HTML code into Confluence so you can measure traffic in your documentation.
You can now monitor the activity and traffic for every page you create in your Confluence instance and technical documentation.
Hint: If you want to measure the effectiveness of a particular space within the 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.
This is a useful suggestion. Once you have set up your first documentation space and are more-or-less happy with it, use the Copy Space plugin (see notes below) to copy the space while it still has very little content. From this point on, you can copy it each time you want to create a new documentation space.
You now have a template space. From this point on, you can use the Copy Space plugin to copy the template space each time you want to create a new documentation space.
- The Copy Space plugin is not covered by Atlassian support. However, the Atlassian technical writers use it for all our documentation. If you like, you can vote for an comment on the request for Atlassian support to cover this plugin: CONF-14198.
- Your site administrator will need to install the Copy Space plugin into Confluence. Refer to the documentation on installing plugins