There’s no doubt that content is the important component of technical documentation. The visual appeal of the documentation is a close second. Ultimately, the effectiveness of your content is dependent on how well it can actually be read. In this post we share five features that will dramatically improve the readability and effectiveness of your technical documentation in Confluence.
Note: Detailed instructions and examples of the features below can be found in our documentation – Essential Confluence Features for Technical Documentation
1. Auto-Generate a Table of Contents
Is there anything worse then hopelessly scanning product documentation for an answer? One valuable tool to improve a reader’s chances of finding what they are looking for is to utilize the Table of Contents Macro, which scans the headings of the current Confluence page and automatically generates a table of contents based on the page’s headings. This helps readers navigate lengthy pages by summarizing the content structure and providing links to headings further down the page. A reader can then skip the irrelevant parts of the page and jump right to the content they need.
The image below (click to enlarge) shows the Table of Contents macro inserted at the top of release notes page in Confluence. Note that we have excluded the ‘Highlights of Confluence 3.4’ heading from the table of contents by modifying the macro’s parameters.
2. Put Content Inside Customisable Panels
The Panel Macro allows you to display anything from a block of text, to an image or embedded video inside a customisable panel. Generally, the purpose is to accentuate content or define sections within a page. Panels are an important visual tool to improve the readability of a Confluence page – providing balance and distinction between blocks of content.
Typically, a panel is used to separate instructions from contextual background. The default setting for a panel inserts a gray panel on to the page behind the desired text. You can also customise panels in a variety of ways – background color, panel title, border color – using the Macro Browser.
3. Draw Attention to Elements of a Page
The Note, Info, Tip, and Warning macros make it easy to highlight important content on a page. Each macro displays a different color and icon to signify a different meaning. Click the image below for examples.
4. Hide Content Inside Expandable Boxes
The Expand Macro helps prevent your technical documentation from becoming too cluttered by allowing you to hide large chunks of information, condense answers to FAQs, or to hide embedded code and video, in an expandable text box. Click the image below for an example.
Note: The Expand Macro is not bundled and must be added by a Confluence Administrator.
5. Engage Readers by Embedding Rich Content
Text-only documentation is a thing of the past. With technical documentation shifting online, its important to start adding media and video to keep up with the times. Confluence comes bundled with the Widget Connector Macro which allows you to embed content from popular websites into your Confluence page. For example you can embed videos from YouTube, user timelines and mentions from Twitter, documents and presentations form SlideShare and Google Docs, forms from Wufoo, and communities from Get Satisfaction. Those are just a few examples, there are many, many more.
Try embedding a ‘What’s New’ video, hosted on YouTube, in your next set of release notes. Click the image below to see examples of the types of content you can embed.
Try Them Now
All of these macros are available to test out in the Confluence Sandbox. Simply create a page and launch the Macro Browser to try all five of these macros and see how they can improve the look and feel of your documentation.
New to Confluence?
Learn more about using a wiki for technical documentation in our Technical Communicators Guide to Technical Writing in a Wiki.