Out of the box, Confluence is beaut. Add a plugin or two, and your documents glow. So which plugins do we use in the Atlassian product documentation?

Here at Atlassian, we use a wiki for almost all our product documentation. On our Confluence site, you’ll find user guides, administration guides and other technical documentation for Bamboo, Clover, Crowd, Crucible, Fisheye and of course for Confluence itself.
* Quick quiz: Which product is missing? Answer is at the bottom of this blog.

To add extra structure and style to our documentation, we use the macros provided by some Confluence plugins. We limit ourselves to just a few plugins, because we’re aware that many customers download our documentation in XML format and upload it into their own Confluence installations. And they don’t necessarily have the same plugins installed as we do.

Giving it some structure

The question we’re asked most often is this:

How do you get that dynamic table of contents in the left-hand panel?

We’ve inserted the pagetree and pagetreesearch macros into the page layout for most of the documentation spaces. You can find some guidelines here. Below is an example. (Click the image to open an expanded view, and click the link below the image to go to the documentation page itself.)

Example 1

View the real page.

The {pagetree} macro generates the table of contents on the left. It shows the pages in the space, starting from a given level in the page hierarchy.

We use {pagetreesearch} to confine the search results to a space, or even a lower-down hierarchy of pages. This is great when you have a large Confluence instance, where the search results can be a bit overwhelming.

The toc macro (see example 2 below) generates a table of contents from the headings on a single page. You can limit it to show only a given level of headings. In our release notes, we’ve used {toc:minLevel=2|maxLevel=2}. So we can use the ‘h1’ level of heading as a section break, without it appearing in the table of contents. In the example below, ‘Highlights of Confluence 2.6’ is a level-1 heading and ‘Fresh look for the Default theme’ is the first of the level-2 headings.

Example 2

View the real page.

To show ‘related topics’ and mini tables of contents, we use the children macro (not illustrated here) and the contentbylabel macro (see example 3 below). We find the {children} macro useful for a carefully-structured hierarchy of documents, whereas {contentbylabel} is handy for a more loosely-associated set of pages such as FAQs and ‘related topics’.

Example 3

View the real page.

To repeat information on more than one page, such as introductions and overviews, try excerpt-include and include. (Not illustrated here.)

Making it look good

Confluence allows you to upload and display ready-made images and photographs. In addition, you can create and edit images and diagrams within Confluence itself, using the Gliffy plugin. Here’s an example:

Example 4

View the real page.

To make a note stand out from the rest of the page, we’ve enclosed it in a panel and made it float to the right of the page. See example 5 below. The {float} macro is part of the Composition plugin.

Example 5

View the real page.

The section and column macros give our pages some structural style. You can see them in action in examples 1 and 2 above. For other pretty layout effects and emphasis, try note, warning, tip (see example 3 above) and info. To preserve formatting in code and other extracts, we use code and noformat. (Not illustrated here.)

Archiving documents and managing releases

We provide a separate set of documentation for each major release of a product. For example, the current Bamboo space contains documentation relating to the most recent Bamboo release. And there is an archive space for Bamboo 1.1.

To create the archive copies of the spaces, we use the Copy Space plugin (still in a beta release).

More about macros and plugins

  • Plugins are add-ons to Confluence. Some plugins are pre-installed in Confluence. Your Confluence administrator can decide whether to install others.
  • A plugin may allow you to use one or more macros on your Confluence pages. (More about using macros).
  • Take a look at the full list of Confluence plugins and the documentation for each of them.
  • To see which macros a plugin contains, administrators can go to the Plugin Repository on your Confluence instance and click the plus sign under the plugin name. The Plugin Repository page will also tell you whether the plugin is installed on your version of Confluence.
  • Not all plugins are officially supported by Atlassian. Refer to each plugin’s documentation page in the plugin list for information about its status. The macros shipped with Confluence are listed in the Confluence User Guide.
  • Tip: To see the macros and other markup which generates a specific wiki page, go the ‘Info’ tab of the page and click the ‘View Source’ link near the top right of the tab.

* Answer to the quick quiz: Jira, of course. The Jira documentation is housed in Apache Forrest at the moment. We plan to move the documentation to the wiki soon.

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now