Develop Technical Documentation in Confluence

Confluence is a flexible platform with a range of features and Marketplace apps that can help you capture, distribute, and update your technical documentation. Below are some tips to help you get your technical documentation site started, and to save you time and effort managing your documentation's life cycle.

For another great overview of how you can use Confluence for documentation check out Rock the Docs from our solution partner, K15t. 

Create your Documentation Space

Creating spaces in Confluence is quick and easy. All you need to do to get your documentation started is choose Spaces > Create space from the Confluence header. To make things even easier, choose the 'Documentation Space' option in the create space dialog; it'll give you a custom home page with a search box (the livesearch macro) to search just your documentation space, a recently updated macro, and a few other goodies.

Give your space a name, and Confluence will automatically create the home page and space key for it (change the space key if you're not happy with the one Confluence chooses for you). Feel free to customize the home page at any time; what it looks like is completely up to you!

---

Save time by re-using content

If there's something you're going to use multiple times in your documentation space – whether it's a word, sentence or paragraph; an image; a product version number; or anything else – you can create it once and include it on as many pages as you like (or use it in the header and/or footer). Inclusions not only save you typing the same thing many times, they also make it easier when things change – it's much better to update the info in one place, than 47!

On this page:

Related pages:

• Spaces

There are 3 macros that allow you to re-use content:

• The  Excerpt macro  to define a re-usable section, or 'excerpt', on a page – add content inside this macro, and you can reuse it on as many pages as you like.
• The  Excerpt Include macro  (excerpt-include) to include the contents of an excerpt on another page.
• The  Include Page macro  (include) to include the entire content of a page on another page.

For example, let's say you create release notes for each major release of your product, and you want to include the intro from each release notes page on a 'what's new' page. Place each release notes intro in an Excerpt macro, then add an Excerpt  Include macro for each set of release notes to the what's new page. Your intros will magically appear on the what's new page, and if you update the release notes it'll automatically update the what's new.

1. Excerpts: the intros to these pages are in excerpt macros. 
2. Excerpt include: these are excerpt include macros. 

Another example is one of the ways we use the Include Page macro. Whenever the ellipsis (

) appears in our documentation – for example, go to   > Copy – it's actually an Include Page macro. We have a page with just that image on it, so we can include it whenever we need an ellipsis.

Why do we do use an Include Page macro for one tiny image? Well, just in case that UI element is ever changed. If we attach the image to every page, there might be 50 pages we need to update when things change; if we use an Include Page macro, we update once and it's changed everywhere. Doing it this way also allows us to know how many pages we're using the image on. By going to 

 > Page Information, we can see how many incoming links there are to this page, and that tells us how many pages use the image.

Create an inclusions library (optional)

You can include content from any Confluence page, but you may want to create an 'inclusions library' to hold content that's specifically for re-use. The inclusions library isn't a specific feature of Confluence; the pages in the inclusions library are just like any other Confluence page. This is just a technique you can use if you want a place to store content that's specifically for re-use.

To create your inclusions library:

1. Choose Create and create a new page in your space
2. Enter a suitable title. We use '_ConfluenceInclusions' (the underscore before the title helps to let people know this page is special)
3. Enter some content and save the page
   We enter text explaining the purpose of the inclusions library and how to re-use the content
4. Choose Space tools > Reorder pages and drag your new page above the space homepage
5. Go to your new inclusions page and choose Create to add child pages containing your re-usable content

Because you've moved the pages to the root of the space, they won't appear in the page tree in the sidebar. The pages will be picked up by other searches though, as they're normal Confluence pages.

1. Inclusions library location: drag your inclusions library here, above the rest of your documentation. 

---

Use page templates

Creating one or more page templates can be a real time-saver if you're creating a lot of pages with the same layout. If you're constantly adding the same macros, like panels and table of contents, save yourself from RSI and put them into a template – you can start with one, but make as many as you need to maximize your efficiency.

To create a page template that's available in all spaces:

1. Go to 

   Error rendering macro 'includeplus'

   User 'anonymous' does not have permission to view the page with ID 1255454939.

2. Select Global Templates and Blueprints from the list on the left
3. Choose the Add global page template button at the top-right
4. Create your template page and choose Save

For detailed info on page templates, see Create a Template.

---

Draft your work

When you're creating a new page in your documentation, you'll likely want to do it over time, saving as you go, and have a select few people review it to provide feedback. A loose description of this workflow is 'draft, review, publish'.

You don't want any half-finished pages being seen by your users, and most documentation needs to be reviewed before it's finalized, so here's a technique for drafting pages and allowing for review:

1. Create a page and restrict its permissions
   For example, you might restrict viewing to a group of people such as your team, or a few select individuals. On a public site, you might restrict viewing to staff members, so that the general public can't see the page.
2. Write your page content
3. Share the page with your reviewers and ask them for feedback (make sure you haven't restricted them from seeing the page!)
   The reviewers can add comments to the bottom of the page or highlight text to add a comment inline. If you give them permission, they can also edit the page content directly.
4. Publish the page when ready, by doing the following:
   1. Delete any comments on the page
   2. Remove page restrictions so that your audience can see it

You've now published your page. The space permissions and site permissions now determine who can see and/or update the page.

---

Use links and anchors

Add links

In any documentation site, it's essential to be able to link from one page to another, and often to specific sections on a page. You can add any URL to a Confluence page and Confluence will automatically detect it and turn it into a link.

If you paste the URL for another page in your Confluence site, Confluence will display the link text as the page name and turn it into a relative link, meaning if the name of the page changes, Confluence will adjust the link so it doesn't break.

Add and link to anchors

The anchor macro allows you to create anchors in your documentation, which can be linked to from anywhere. I've added an anchor at the top of this page so you can click to go back to the top.

To add a macro and link to it from the same page:

1. Type {anchor in the editor, select the anchor macro and give your anchor a name (top in my example)
2. Select the text that'll link to the macro and hit Ctrl+K (Windows) or Cmd+K (Mac) (this opens the link dialog)
3. Choose Advanced from the options on the left and type # followed by your anchor name (#top in my example)

Check out our documentation for links and anchors to get the full rundown on linking to anchors on other pages and other anchor goodness.

---

Useful macros

Confluence ships with a great range of macros, and there are a few that are particularly useful in technical documentation. Here's a few:

Table of contents macro

The Table of Contents macro helps people navigate lengthy pages by summarizing the content structure and providing links to headings used on the page. The best part is, you don't need to do anything except add the macro; once you've added it, it'll automatically detect headings and add them to the table of contents.

Tip, Note, Info, Warning, and Panel macros

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 Tip, Info, Warning, Note and Panel macros, which will help you focus a viewer's attention on a particular part of your content.

---

Keep track of page updates

In Confluence, it's quite usual for a number of different people to update a single page. Technical writers need to know what happens to our documents, both during review and after publication.

Watch pages or the space

So that you know when changes are made, it's a good idea to  watch  pages or even the entire space. That way, when changes are made to pages you're watching, or someone comments on them, you'll get an email notification letting you know who changed what.

Whenever you're on a page in your documentation space, choose the Watch button at the top-right of the page. From there, you can choose to watch just that page, or all pages in the space.

View page history

Confluence creates a new version of the page every time someone edits the page. The page history shows all the versions, with date, author, and any comments made on the update.

To view page history, go to the page and choose 

 > Page History

On the page history view, you can:

• View the content of a specific version of the page.
• Revert to (restore) a specific version.
• Select any two versions and ask for a comparison, to see what has changed between those two versions.

Take a look at Page History and Page Comparison Views for a detailed explanation.

Show a list of contributors

If you want to see at a glance who's updated a page or pages, you can add the contributors macro. This macro displays a customizable list of people who've contributed by creating, editing, or, optionally, commenting on the page.

---

Customize PDF export

If you're planning to provide a PDF version of your documentation – whether it be for email, download, print, or any other form of delivery – you can customize the look of the PDF by adding a title page, header, and footer.

The process you take depends on whether you're trying to customize the PDF export for one space or for your whole site, so, if you're keen to make these changes, take a look at our page on Customize Exports to PDF for more detailed instructions.

---

Other useful tools and apps

Confluence is already a great tool for technical documentation, but you can still add to it depending on your documentation and workflow needs. Here are some useful apps available on the Atlassian Marketplace, most of which we use ourselves, which can extend the functionality of Confluence.

New apps are hitting the marketplace all the time. This is by no means an exhaustive list!

Scroll Versions (supported by vendor)

Scroll Versions, by K15t, allows you to tie versions of your documentation to versions of your product, so that when a new version of your product ships you can publish that version of your documentation. Create as many versions of your documentation as you like, make the changes you need to, and keep them up your sleeve until release time. You can even publish different variations of your documentation – like if you have versions of your documentation for different operating systems – to different spaces or Confluence instances.

Copy Space (unsupported)

The Copy Space add-on, by Atlassian Labs, does what its name suggests; it allows a space administrator to copy a space, including the pages within the space. Great for when you want a space template that you can copy to create other spaces.

This app is also useful when you need to archive a copy of a current space at a particular point in time, like when you're moving from one version of your product to the next – copy the space, give it a new name, and keep it wherever you like, all without losing the existing space.

 At this point this plugin won't copy page history, blog posts and email.

Scroll PDF Exporter (supported by vendor)

If you're going to produce a PDF of your documentation space, wouldn't you like it to be professionally formatted? The Scroll PDF Exporter, by K15t, lets you style single pages or whole spaces for export, using handy PDF templates.

Gliffy (supported by vendor)

Create diagrams, wireframes, flowcharts and more with Gliffy. Gliffy features a highly intuitive drag-and-drop interface, and allows you to export your diagrams in multiple formats, including: JPEG, PNG and SVG. Add Gliffy flowcharts, UI wireframes, and network diagrams directly to your Confluence pages to communicate your ideas visually, making them easy to understand and faster to spread through your team.

Lucidchart (supported by vendor)

Lucidchart is available in versions for Cloud and Server, and allows you to create and insert diagrams within your Confluence Cloud environment. Quickly draw flowcharts, wireframes, UML diagrams, mind maps, and more inside our feature-rich editor.

The server version also comes with a free Visio viewer, so you can view Microsoft Visio (.vsd) files, Visio stencils (.vss) and it also supports exporting back to Visio.

Documentation theme (discontinued)

Confluence historically provided a theme specifically for documentation. This theme was removed in Confluence 6.0.

A number of the original Documentation theme features, such as headers, footers and the ability to add custom content to the sidebar, are available in Confluence's more modern default theme, which make it a great choice for your documentation space.