Essential Confluence Features for Technical Documentation

This page is part of the guide to developing technical documentation on Confluence. In this section we highlight the built-in Confluence macros that are most useful in technical documentation. For more information about Confluence macros, see Working with Macros.

On this page:

Auto-generating a table of contents for page content

It is important to make it easy for viewers to jump to the section of a Confluence page that they are most interested in. The Table of Contents macro helps people navigate lengthy pages by summarising the content structure and providing links to headings used on the page.

  Click here to see a common example >>
  1. You document the Release Notes for the latest version of your product in a Confluence page.
  2. Each feature in the release is a heading on the page.
  3. You can generate a list of hyperlinks to each of the features in the release notes by inserting the Table of Contents macro:
  4. The image below shows the Table of Contents macro inserted at the top of the 'Release Notes' page. Note that we have excluded the 'Highlights of Confluence 4.0' heading from the table of contents by modifying the macro's parameters.
  5. The image below shows the macro parameters specified in the macro browser. Note the 'Minimum Heading Level' and 'Maximum Heading Level' parameters.

Return to top of page

Drawing attention to elements of a page

Often when creating documentation there are elements of a page that you want to highlight, or draw the the viewers' attention to. Confluence ships with the following macros that help you focus a viewer's attention to a note, information, tip or warning.

  Click here to see a common example >>
Note macro

What is it?

Example

The Note macro allows you to highlight a note on a Confluence page.

It creates a yellow coloured box surrounding your text, as shown to the right.

See Note Macro for more examples and instructions.

Draft in progress

This document is a draft and is under development.

Info macro

What is it?

Example

The Info macro allows you to highlight helpful information on a Confluence page.

It creates a blue coloured box surrounding your text, as shown to the right.

See Info Macro for more examples and instructions.

Did you know?

Confluence is the best wiki ever.

Tip macro

What is it?

Example

The Tip macro allows you to highlight a helpful tip on a Confluence page.

It creates a green coloured box surrounding your text, as shown to the right.

See Tip Macro for more examples and instructions.

Warning macro

What is it?

Example

The Warning macro allows you to highlight a warning note on a Confluence page.

It creates a red coloured box surrounding your text, as shown to the right.

See Warning Macro for more examples and instructions.

Draft

This page is a draft in progress and visible to Atlassian staff only.

Return to top of page

Putting content inside customisable Panels

Using the Panel macro, you can place content inside a customisable coloured panel. This is particularly useful when you want to clearly separate elements on a page.

  Click here to see a common example >>
  1. You are documenting a procedure which involves a number of steps.
  2. You want to call out the steps of the procedure from the rest of the page by placing it inside a coloured box, or panel.
  3. You can create a coloured panel using the Panel macro.
  4. The image below shows the parameters set for the panel using the macro browser.

Return to top of page

Inserting anchor links on pages

Anchor links can be especially useful when navigating between sections of a long document or when you want to link to a segment of a page from another page. The Anchor macro allows you to link to specific parts of a page.

  Click here to see a common example >>
  1. You are documenting part of a user guide.
  2. The page is split into multiple sections.
  3. After each section you want to provide a link for viewers to click, taking them back to the top of the page.
  4. To achieve this you first must create an anchor at the top of the page using the Anchor macro. You can give the anchor any name you like. In the image below, the anchor at the top of the page will be named 'top'.
  5. The anchor placeholder will appear to indicate where your anchor link is located on the page:
  6. Create a link to the anchor, anywhere on the page, using the Link Browser. The image below shows a link to the anchor called 'top' by using the hash '#' followed by the name of the anchor you created earlier, with an alias of 'Return to Top'.

See Working with Anchors for more examples and instructions.

Return to top of page

Structuring content using sections and columns

Sometimes it is necessary to structure content into sections and columns. The details are in Working with Page Layouts and Columns and Sections.

  • Page layouts allow you to add sections to your page and then apply pre-defined column layouts to each section (for example, 2 column, three column). You can add multiple sections to a page. 
  • The Section and Column macros allow more flexibility. You can set the width of the columns, and put the sections and columns in any part of the page. Each section can contain any number of columns, created using the Column macro.
  • Columns can either have a fixed width, specified in pixels, or a dynamic width, specified as a percentage of the page width.
  • Note: whether you are using page layouts or macros, a column is always created inside a section.
  Click here to see a common example >>

The images below show part of a Confluence page with two sections (outlined in red), each with two columns (blue) of different widths.

  1. Section 1:


  2. Columns in section 1 – left column has a fixed width of 400 pixels:


  3. Section 2:


  4. Columns in section 2 – left column has a fixed width of 10 pixels:

Return to top of page

Making your documentation more engaging by embedding videos

Pictures can be worth a thousand words. The same can be said for videos. Often, it's easy to explain a concept or demonstrate a procedure using a video. The Widget macro allows you to embed web content, including YouTube and Vimeo videos, in a Confluence page.

  Click here to see a common example >>
  1. You release a new version of your product.
  2. You document the release notes on a Confluence page.
  3. The marketing team creates a video demonstrating the new features of the release and uploads it to YouTube.
  4. You can embed the video in your release notes using the Widget macro, for playback on your Confluence page.
    1. Edit the page and choose Insert > Other Macros in the editor toolbar.


    2. Search for the 'Widget Connector'.


    3. Insert the URL of your YouTube video into the Web Sites Widget URL field.


    4. Choose Insert and save your page.

See Widget Connector Macro for information on the supported services and for more examples.

Return to top of page

Next steps

Take a look at Confluence Add-ons for Technical Documentation.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport