Confluence 3.5 : Re-using Content in Technical Documentation
This page last changed on Dec 31, 2010 by smaddox.
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.
The rest of this page gives an overview and more details of the above procedures. Reasons for Re-Using ContentA 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:
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 LibraryWe 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 InclusionsExcerpts and inclusions (sometimes called 'includes') are very useful for re-using content:
A simple example of 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 MacroIn 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 MacroAn 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 PluginThe 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:
See the Multi Excerpt plugin page for more details. An Example of Content Re-Use: A GlossaryA 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:
Once you have defined the glossary entry, you can refer to it from the main pages of your technical documentation. Creating a One-Page GlossaryThis 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 PagesThis 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 TermsIn the main pages of your technical documentation, create a link to the glossary page for each glossary term. _[MyGlossary Term|Glossary#MyGlossaryTerm]_ 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 StepsYou 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. |
![]() |
Document generated by Confluence on Mar 16, 2011 18:25 |