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 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.)
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.
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.
- 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.
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.
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.
See the glossary in the Crowd documentation for an example of this style of glossary.
Referring to Glossary Terms
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.