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
excerptmacro 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-includemacro to include the excerpt from one page onto another page.
- Use the
includemacro to include the entire content of a page onto another page.
- Consider installing the Multi Excerpt add-on 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, 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 use case for an inclusion is a note or warning that is used in many places in your documentation. Here is an example:
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.
- Create a page in your inclusions library called _Draft Note.
Add the content of the page. In this example, we use the Note macro with some text in the title and body:
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.
excerptmacro 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':
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 add-on' below.
Using the Multi Excerpt add-on
The Multi Excerpt add-on 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 provided by the Multi Excerpt add-on are very useful.
- The Multi Excerpt add-on is a commercial add-on and is not free.
- Your Confluence system administrator will need to download and install the add-on into your Confluence site before you can use the macros described below. Refer to the documentation on installing add-ons.
- 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. Please refer to the Multi Excerpt add-on page for support details.
To have multiple excerpts on a page:
Use the following code on the base page containing the content you want to use elsewhere:
Use the following code on the page where you want to include the named excerpt:
You can also include excerpts from other spaces using the following syntax:
See the Multi Excerpt add-on 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. The code blocks below use wiki markup. To insert wiki markup onto your page, open the editor and chose Insert > Wiki Markup.
- Create a page named Glossary.
Add an alphabetical index at the top of the page and a heading for each letter of the alphabet:
- Enter each glossary entry under the relevant alphabetical heading. Each glossary entry (term) should include:
anchortag, 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.
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. The code blocks below use wiki markup. To insert wiki markup onto your page, open the editor and chose Insert > Wiki Markup.
- Create a page named Glossary.
- 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
On the 'Glossary' page, use the
childrenmacro 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.
A blog post about content re-use: Technical Writing in a Wiki - Content Re-use and Structure (November 2010).
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.