Confluence Add-ons for Technical Documentation

Commercial or free? Commercial.

Alternatives: As an alternative you can use the standalone version of Gliffy available at http://www.gliffy.com/. Gliffy online has a free basic version.

More information: See the Gliffy add-on page.

Lucidchart

Using Lucidchart, you can draw flowcharts, wireframes, UML diagrams, mind maps, and more, inside the web editor, then integrate the diagram with Confluence. Include interactivity such as linking to pages within Confluence or other pages inside the diagram.

Commercial or free? Commercial.

More information: See the Lucidchart add-on page.

Creately

Use Creately to draw flowcharts, UML diagrams, database diagrams, wireframes, mindmaps, UI mockups, workflow diagrams, network diagrams, org charts, and Gantt charts.

Commercial or free? Commercial.

More information: See the Creately add-on page.

yWorks Diagrams

Use yWorks Diagrams to create and edit diagrams directly inside Confluence.

Commercial or free? Commercial.

More information: See the yWorks Diagramsadd-on page.

Add-ons for enhanced content manipulation

All content extensions are provided by macros in Confluence. Some macros are built in to Confluence. Other macros are supplied by add-ons.

Quick overview of macros

Before looking at add-ons, let's take a quick look at macros in general. There are two ways to add a macro to your page:

• Use the macro browser. This is the simplest and recommended way.
• Or insert the macro's name in curly brackets into the text of your page and specify the parameters.

Some content on my page.
{include:My Page}
Some more content on my page. 

A number of macros are shipped with your Confluence installation by default. See Working with Macros. Below we describe some add-ons that provide additional useful macros for Confluence:

Composition add-on

The Composition add-on provides macros which allow finer control over the layout (composition) of a page. Using these macros, you can:

• Outline your text blocks.
• Add tabs to a page.
• Flow your text around the images or diagrams on the page.

Commercial or free: Commercial.

Using the Composition add-on to outline text blocks

Use the {cloak} macro to outline a text block.

Usage: The following code creates a text block named 'SeeAlso' for the outlined 'See Also' section within a page. The text block with id='SeeAlso' will be hidden after the 'See Also' title:

{composition-setup}
h2. {toggle-cloak:id=SeeAlso} See Also
{cloak:id=SeeAlso}
h3. Working With Macros:
[Link 1]
[Link 2]
h3. Working with Rich Text Editor:
[Link 3]
[Link 4]
{cloak}

Alternatives: You can also use the {expand} macro available in Confluence by default, but this macro can outline only text of the same level and cannot hide headings within the text. The {expand} macro does not require parameters and just hides the text placed between the {expand} tags.

Note: If you need to outline a text block containing nested headings, consider the text structure. Maybe the block is too big. You could create a child page from this block to decompose the whole text. Then you can include and outline the text block using the {include} macro within {expand}.

Using the Composition add-on to add tabs to a page

Use the {deck} and {card} macros to separate content between tabs on the same page.

Usage: The following code creates two tabs with client information:

{composition-setup}
h1. Client Name
{deck:id=ClientName}
{card:label=Basic}
Client Company Name: Company
[Client Web Site|http://url.com]
Our projects: [Project1|Project1 Home]
{card}
{card:label=Contacts}
Company CEO: John Brown, e_mail: brown@company.com
{card}
{deck}

The tabs on a page will look like this:

Using the Composition add-on to flow your text around images

Use the {float} macro to make your text flow around images or diagrams.

Usage: The following code demostrates how a picture can be surrounded by the description, as often shown in printed publications:

{composition-setup}
{float:left}
!shakespeare.jpg!
{float}
William Shakespeare (baptised 26 April 1564; died 23 April 1616) was an English poet and playwright, widely regarded as the greatest writer in the English language and the world's pre-eminent dramatist.
...

The page will look like this:

For more macros, see the Composition add-on page.

Scaffolding add-on

The Scaffolding add-on provides macros for creating 'permanent templates' and editable forms. You can create sophisticated page templates in order to add content easily and fast. Scaffolding templates are suitable for dynamically-filled data and allow people to create pages by completing form fields and selecting values from drop-down lists.

The Scaffolding templates are useful for creating pages with a well-determined structure, such as:

• API methods or property descriptions.
• Constant list.
• Feature description.
• Software requirement specifications.

Commercial or free: Commercial.

Example: The following Scaffolding template creates a description of an API method:

h3. Method Name
{text-data:methodName|required=true}{text-data}
h3. Method Description
{text-data:methodDescription|type=area|required=true|width=100%}description{text-data}
h3. Parameters
{table-data:parameters}
|| Name || Type || Mandatory || Description ||
| {text-data:paramName}ParamName{text-data} | {list-data:paramType}{list-option:Number}Number{list-option}{list-option:String}String{list-option}{list-option:DateTime}DateTime{list-option}{list-option:MACaddress}MACaddress{list-option}{list-option:IPaddress}IPaddress{list-option}{list-data} | {list-data:paramMandatory}{list-option:Required}Required{list-option}{list-option:Optional}Optional{list-option}{list-data} | {text-data:paramDescription|type=area}param description{text-data} |
{table-data}
h3. Return Value
The returned value is an XML structure of the following format:
\{code:xml\}
\{code\}
Where elements mean:
{table-data:returnValues}
|| Name || Type || Description ||
| {text-data:paramName}ParamName{text-data} | {list-data:paramType}{list-option:Number}Number{list-option}{list-option:String}String{list-option}{list-option:DateTime}DateTime{list-option}{list-option:MACaddress}MACaddress{list-option}{list-option:IPaddress}IPaddress{list-option}{list-data} | {text-data:paramDescription}param description{text-data} |
{table-data}
h3. Remarks
{text-data:remarks}remarks{text-data}
h3. See Also

This template will look like this:

For more information on how to create templates in Confluence, see Creating a Template.

Alternatives: Confluence includes built-in templates which as useful for static data and simple text. For more information, see Working with Templates.

Notes: The Scaffolding (and any) template changes will affect only new pages created from the modifed template. In order to change the existing pages, you need to edit each individual page and add or modify the formatting manually.

For more information on Scaffolding, see the Scaffolding add-on page.

Extended version control

Scroll Versions

Scroll Versions adds functionality for sophisticated version management, enhanced content reuse, support for context-sensitive help, permalinks, and duplicate page titles. You can set up and manage concurrent versions of your documentation in a single space. Multiple versions of software, different product variants, and even multiple translations of documentation can be managed. Changes to pages are scheduled for a specified version and then published all at once. See the Scroll Versions documentation for an overview of the key features.

Commercial or free: Commercial.

Video: Scroll Versions - Version Management for Confluence (4:20)

Attachment Checkout add-on

The Arsenale Lockpoint: Attachments Checkout adds check-out/check-in functionality for Confluence attachments.

Commercial or free: Free for up to 50 users, then commercial.

More information:

• Please visit the Attachments Checkout add-on page for an overview, including a video,
• See the Attachments Checkout documentation for further reference.

Add-ons featured in other parts of this guide

• Copy Space add-on – Provides an easy way of copying a space within a Confluence site. Free. See Creating your Technical Documentation Space.
• Multi Excerpt add-on – Enables you to have more than one excerpt (re-usable chunk) on a page. Commercial. See Re-using Content in Technical Documentation.
• Ad Hoc Workflows add-on – Provides advanced workflow features. Commercial. See Managing the Life Cycle of your Technical Documentation.
• Content Publishing add-on – Publishes content from a master space to a published space. Commercial no charge. See Managing the Life Cycle of your Technical Documentation.
• Scroll Office – Provides advanced features for export to Microsoft Word. Commercial. See Exporting and Printing Technical Documentation.
• Scroll PDF Exporter – Provides advanced PDF export features. Commercial. See Providing PDF Versions of your Technical Documentation and Exporting and Printing Technical Documentation.
• Scroll DocBook Exporter – Provides DocBook exports. Commercial.
• Scroll EPUB Exporter – Outputs an ebook in the common EPUB format that can be read on iPads, iPhones and any other ebook reader. Commercial.
• Scroll HTML Exporter – Enables the delivery of Confluence content from a web server. It converts the pages into static HTML pages that can be uploaded to a web server. The output of the Scroll HTML exporter can also be used as an input to produce other HTML-based help formats such as WinHelp and HTML Help. Commercial.
• Scroll EclipseHelp Exporter – Enables you to collaborate and author all your content in your wiki, and generate embeddable online help for Eclipse-based applications. Commercial.

Notes

•  Add-on support. 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.

• Installing add-ons. If you decide to use additional add-ons, your site administrator will need to install the add-ons into your Confluence site. Refer to the documentation on installing add-ons.

Further reading

• • A blog post about useful add-ons and tools for exporting and importing content from/to Confluence: Technical Writing in a Wiki - Single Source Publishing (November 2010).
  • Website for exploring and downloading the available add-ons: Atlassian Marketplace.
  • Documentation on installing and configuring add-ons: Universal Plugin Manager documentation.
  • Documentation on using macros: Working with Macros.
  • Further Reading about Developing Technical Documentation on Confluence