Child pages
  • Re-using Content in Technical Documentation
Skip to end of metadata
Go to start of metadata

This page is part of the guide to developing technical documentation on Confluence Wiki. In the page about creating your technical documentation space, we showed you how to set up an 'inclusions library' to contain content that you can re-use on more than one page. Now we offer further guidelines on re-using content in your documentation space.

Your documentation may be about using a software application, or it may be a technical manual for your product range. On this page, we use the term 'widget' to describe the things that you are documenting, such as the screen, form, document, product or object.

Quick guide to re-using content

  • Create an 'inclusions library' to manage your re-usable content. See our guide to creating your technical documentation space.
  • Use the excerpt macro to define a re-usable section ('excerpt') on a page, or just decide to re-use the entire content of the page.
  • Use the excerpt-include macro to include the excerpt from one page onto another page.
  • Use the include macro to include the entire content of a page onto another page.
  • Consider installing the Multi Excerpt plugin if you need to define multiple excerpts per page.

The rest of this page gives an overview and more details of the above procedures.

Reasons for Re-Using Content

A golden rule for technical documentation is to write the content only once but allow that content to be used in many places and in many forms.

For example, you may have the following types of content:

  • A technical manual that describes each widget in detail.
  • Tips and tricks on how to get the most out of the widget.
  • A step-by-step user guide for first-time users on how to use the most common widgets.
  • A training manual with exercises or videos that people can follow in their own time.
  • A one-page cheat sheet for users to stick up on their workstation.
  • Text for a sales brochure that is sent out to a print house for production.

Each of these types of content will share common information, such as a glossary entry, a technical or marketing description of the widget, or a step-by-step guide on how to use the widget.

Some initial planning of your technical documentation will allow you to re-use any or all of the content you write, so there is only ever one place to update the content, and those changes flow through to all of your other documentation.

Defining an Inclusions Library

We recommend that you create an 'inclusions library' to manage your re-usable content. If you have not already done this when creating your documentation space, see our guide to creating your technical documentation space.

Working with Excerpts and Inclusions

Excerpts and inclusions (sometimes called 'includes') are very useful for re-using content:

  • Use the Excerpt macro (excerpt) to define a re-usable section ('excerpt') on a page.
  • Use the Excerpt Include macro (excerpt-include) to include the excerpt on another page.
  • Use the Include Page macro (include) to include the entire content of a page onto another page.

A simple example of an inclusion is a note or warning that is used in many places in your documentation. Here is an example:

Example note -- "Draft in progress"

This document is still in draft status. Please treat the content with caution.

Tip: Keep your re-usable pages short and sweet. Do not worry if you find that you need hundreds of pages to hold your inclusions. It helps to keep things separate and organised.

Using the Include Page Macro

In this example, we use the Include Page macro to create a note that you can re-use on your documentation pages. The Include Page macro will include the entire content of one page into another page. (See the 'Excerpt' macro below for including parts of a page.)

  1. Create a page in your inclusions library called _Draft Note.
  2. Add the content of the page. In this example, we use the Note macro with some text in the title and body:
  3. Use the Include Page macro to include that note in any page in your documentation. For example:

See the documentation on the Include Page macro for more details.

Using the Excerpt Include Macro

An excerpt is a section of a page that you can include into another page.

  1. Use the excerpt macro to define any content in your page that you want to be able to use elsewhere. This content can be as short as a word or as long as the entire page. For example, let's assume we have a page called 'My Short Poem':
  2. Use the Excerpt Include macro to include the excerpt into another page. For example:

You can only define one excerpt on a page. See the documentation on the Excerpt Include macro for more details.

To have multiple excerpts on a page, see the 'Multi Excerpt plugin' below.

Using the Multi Excerpt Plugin

The Multi Excerpt plugin provides additional macros that enable you to have multiple excerpts on a page. A good example of where you would find this useful is in the glossary page discussed below. If you want to include a single glossary entry or a subset of the glossary entries in another page, then the named excerpts allowed by the Multi Excerpt plugin are very useful.

Notes:

  • The Multi Excerpt plugin is a commercial plugin and is not free.
  • Your Confluence administrator will need to download and install the plugin into your Confluence site before you can use the macros described below. Refer to the documentation on installing plugins
  • Before installing a plugin into your Confluence site, please check the plugin's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on plugin support. Please refer to the Multi Excerpt plugin page for support details.
  1. Use the following code on the base page containing the content you want to use elsewhere:
  2. Use the following code on the page where you want to include the named excerpt:
  3. You can also include excerpts from other spaces using the following syntax:

See the Multi Excerpt plugin page for more details.

An Example of Content Re-Use: A Glossary

A glossary is something that most technical documentation will require. There are a few ways to set up glossaries in Confluence. These are the most popular:

  • All glossary entries on one page.
  • Each glossary entry on separate child pages with a main page showing excerpts of the glossary.

Once you have defined the glossary entry, you can refer to it from the main pages of your technical documentation.

Creating a One-Page Glossary

This style of glossary is useful if the glossary entries tend to be short and there are not too many of them.

  1. Create a page named Glossary.
  2. Add an alphabetical index at the top of the page and a heading for each letter of the alphabet:
  3. Enter each glossary entry under the relevant alphabetical heading. Each glossary entry (term) should include:
    • An anchor tag, so that you can link to it from other pages.
    • The term itself.
    • A definition of the term.
    • A link to the page in your technical documentation that explains the term in greater detail, where relevant.
  4. Optionally, include a horizontal line between the terms. This depends on how long each entry is. If your glossary tends to have short entries, it may look too cluttered with horizontal lines.

See the glossary in the Confluence documentation for an example of this style of glossary (without the alphabetical index).

Creating a Glossary with Child Pages

This style of glossary is useful if the glossary entries tend to be quite long or have additional information over and above the definition of the term.

  1. Create a page named Glossary.
  2. Create a child page for each glossary entry (term). Each child page should contain:
    • The term as the title of the page.
    • The definition of the term in the body of the page.
    • Excerpt tags (excerpt) tags surrounding the definition.
    • Any additional information after the excerpt tags.
  3. On the 'Glossary' page, use the children macro to show the excerpts from each child page in a list, with the page name displayed in 'h4' style.

See the glossary in the Crowd documentation for an example of this style of glossary.

Referring to Glossary Terms

In the main pages of your technical documentation, create a link to the glossary page for each glossary term.

Note that this is a standard page link with an anchor. We have formatted the link as italics, because it helps to have the glossary links looking different to other page links. Readers can just skip over the glossary link if they are already familiar with the term.

Further Reading

Next Steps

You now have a good idea of how to re-use content in a Confluence documentation space. What next? Take a look at Managing the Life Cycle of your Technical Documentation.