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 you navigate lengthy pages by summarising the content structure and providing links to headings used on the page.

  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 Leve' 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.

注意マクロ

データ

例

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.

Draft in progress

This document is a draft and is under development.

See Note Macro for more examples and instructions.

情報マクロ

データ

例

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.

Did you know?

Confluence is the best wiki ever.

See Info Macro for more examples and instructions.

ヒント マクロ

データ

例

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.

詳細

Check out this blog post: Technical Writing in a Wiki: Technical Communicators Explain How & Why?

See Tip Macro for more examples and instructions.

警告マクロ

データ

例

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.

下書き

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

See Warning Macro for more examples and instructions.

Return to top of page

Putting Content inside Customisable Panels

The Panel macro allows you to place content inside a customisable coloured panel. This is particularly useful when you want to clearly separate elements on a page.

  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.

  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 offer a set of predefined columns and sections.
  • 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.
  • You can create any number of sections on a Confluence page using the Section macro.
  • 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: A column must be created inside a section.

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, Episodic and Vimeo videos, in a Confluence page.

  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. Select 'Other Macros' from the 'Insert' menu in the Rich Text Editor toolbar.


    2. Search for the 'Widget Connector' in the macro browser.


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


    4. Click 'Insert' and save your page.

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

Return to top of page

次のステップ

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

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.