If you're new to confluence, I highly recommend you try out some macros, so that you can work smarter. Word of warning; I've seen overly macro'ed pages take an age to render. Keep. It. Simple.

The keyboard shortcut in edit mode is {. It gives you an auto-complete of sorts. Explore.

There's lots of cool stuff in there. Here are my favorites.

Add structure to your documentation by listing child pages.

The Children Display Macro will list a tree of child pages. This can be relative to the current page, or it can list the children of a completely different page. This is great for adding structure to documentation...

• as a simple table of contents for a main section on your wiki (remember: not everyone will have the nav panel visible when they follow links)
• or as part of a document that ties together different parts of a wiki. For example a Getting Started, or an on boarding guide that is composed of multiple sections of your wiki but isn't necessarily inside that page hierarchy. This is a great hack for when you need to tie together different pages for different audiences.

Don't repeat yourself.

It can be quite annoying having to follow links. Linking away from a page in confluence disrupts the flow of your document. Sometimes you just want to have everything you need in one page. But what happens when your content belongs on more than one page? Duplication of code is terrible from a code maintenance point of view. Can you imagine how much worse duplication of documentation would be?

Let the Excerpt and the Excerpt Include macros come to the rescue.

Step 1. Create an Excerpt, using the Excerpt macro. This will create a box in edit mode -- and whatever you put into this box becomes the excerpt for the page. As far as I can tell, there's only one excerpt per page (and this is probably a good thing).

Step 2. Create an Excerpt Include macro. This will let you pull in the content you put into that little box. Any changes that get made to the Excerpt appear on all included pages.

Fantastic.

Workaround Confluence's sucky table markdown handling

Confluence's table handling is okay, so long as you use the confluence editor. Importing tables from markdown, however, really, really sucks. You'd think that you should be able to use Confluence's "Insert Markup" to add markdown, but it doesn't.

Meet tablesgenerator.com/markdown_tables

First, go to File > Paste Table Data. Click Load to generate a Result that Confluence can understand. Then, copy the Result, and switch back to confluence.

There, use the Insert Markup macro with your re-formatted table text and make sure it's set to "Confluence Wiki"

Sigh. Problem solved.

(credit to Sean Smith in his community response to a bug posed here: community.atlassian.com/t5/Confluence-quest..)

Get a mermaid to draw diagrams for you

I mentioned this earlier in How to write documentation as if your life depended on it. Diagrams are an efficient way of communicating ideas. Mermaid.js is an efficient way of creating diagrams by letting you treat diagrams like you treat code. Confluence supports Mermaid.js via plugin. marketplace.atlassian.com/apps/1214124/merm...

I don't know about you guys, but the documentation task isn't why I became a software engineer. However it is an important artifact to produce, and for some, an essential part of definition of done. Hopefully these tips will help in making your documentation a useful part of your product.