This documentation relates to an earlier version of Confluence.
View this page in the current documentation or visit the current documentation home.

Skip to end of metadata
Go to start of metadata

This guide is for people who want to develop and publish technical documentation on Confluence wiki. 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

Icon
  • Add a space and select the Documentation theme.
  • Set the space permissions.
  • Change the title and content of the space home page.
  • Customise the Documentation theme.
  • Create an inclusions library to manage your re-usable content.
  • Create the table of contents for your manual or manuals, by adding top-level pages for all the usual sections (user's guide, administrator's guide, and so on).
  • Customise your PDF layout and stylesheet, if required.
  • Hint: Now that you have a good skeleton for a documentation space, save the space as a template space.

The rest of this page gives more details of the above procedure.

Step 1. Add your Space

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 click the 'Add Space' link located above the list of spaces.


    Hint: If you cannot see the 'Add Space' link, this means that you do not have permission to add spaces. Please contact your Confluence administrator.
  2. The 'Create Space' screen appears. 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. Select the 'Documentation Theme'.
  5. Click 'OK'.

The home page 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.

Step 2. Set the Space Permissions

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

  1. Open the 'Browse' menu and select 'Space Admin'.


  2. Click 'Permissions' in the left-hand panel.
  3. Confirm your administrator access as prompted.
  4. Click 'Edit Permissions'.
  5. Set the permissions to suit your needs then click '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.
    • 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.

A Bit 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.
  • 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 your team full edit and administration rights while others can only add comments. Or you might grant the general public access to your documentation, while only staff members can update it.

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, 'Home'. You will want to change the title and content.

  1. Go back to your space home page, by clicking the space name in the breadcrumbs at the top of the screen. In the example below, the space name is 'MyProduct Documentation':
  2. The space home page appears. By default, the page title is 'Home'.
  3. Click 'Edit'.
  4. The page opens in edit mode. 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 home page.
  6. Click 'Save'.

Step 4. Customise the Documentation Theme

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.

  1. Open the 'Browse' menu and select 'Space Admin'.
  2. Click 'Themes' in the left-hand panel.
  3. If the space is not yet using the Documentation theme, apply the theme now.
  4. Click 'Configure theme' in the yellow area of the 'Current Theme' section at the top of the page.


  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. Click '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.

Step 5. Create an Inclusions Library

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. Open the 'Browse' menu and select 'Pages'.
  2. The 'List Pages' screen will appear. Open the 'Add' menu and select 'Page'.
    This will add a page at the root of the space, at the same level as the home page.
  3. Enter a suitable title. We use '_InclusionsLibrary'. The unusual format of the title helps to let people know this page is special.
  4. Enter some content on 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.
  5. Add child pages containing your re-usable content. See the examples of our own inclusions libraries listed 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 home page. 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.

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 documentation, by adding the top-level pages for all the usual sections:

  • User's guide
  • Administrator's guide
  • Installation guide
  • Configuration guide
  • Release notes
  • FAQ
  • Whatever else you need
  1. Go back to your space home page, by clicking the space name in the breadcrumbs at the top of the screen.
  2. Open the 'Add' menu and select 'Page'. This will add the page as a child of the home page.
  3. Enter the page title, 'User's Guide'.
  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 add the Children macro. That will act as a table of contents on the page once you have added child pages.
  5. Click 'Save'.

Now do the same for all the sections of your technical document.

Step 7. (Optional) Customise the PDF Layout and Stylesheet

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.

Step 8. Save your New Space as a Template Space

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.

  1. Open the 'Browse' menu and select 'Space Admin'.
  2. Click 'Copy Space' in the left-hand panel.


    Hint: If you cannot see the 'Copy Space' option, this means that the plugin is not installed on your Confluence site. Refer to the documentation on installing plugins.
  3. The 'Copy Space' screen will appear. Enter the details as prompted, to copy your space to another new space.
  4. Click 'Save'.

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.


Notes:

  • 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.
Next Steps

You now have the basic structure and configuration for your technical documentation space. You have also created a handy template to use next time you need a space. What next? Take a look at Using Templates in Technical Documentation.