How I document everything with Confluence a.k.a. How I nerd out with documentation

Documentation can be your worst nightmare, or if you’re like me – one of your favorite things! I know it can be hard to document, especially if you put it off until the end of a project and then you don’t make time to do it and start another project and never do it. Then 5 months later you get a change request and are kicking yourself for not documenting. Or better yet – someone else is kicking you for not documenting because they got the change request and don’t know where to start. I’ve been on all sides of this scenario, and believe me, you will really want to kick yourself or someone else. But don’t choose violence… just document.

👉 Remind everyone on your team to do it.

👉 Build it into your workflow.

👉 Make it part of your culture.

👉 Talk about it constantly so no one forgets.

👉 Make it fun and pretty.

You can document in lots of places, but my platform of choice is Confluence. I didn’t really choose it per se, it came to me long ago when my company started using Jira for project management, and I just rolled with it. I became an expert at it (and Jira too!) and it has been sooo fruitful. Let me walk you through what I do.

Start With a Hierarchy

You could have the best documentation in the world, but if its not organized then you’ll never be able to find anything and it will be pointless. I like to group by Clouds and by Objects and then more sections for misc. settings. For example, I will have a Sales Cloud main page, and under that main page I’ll have sub-pages for Territory Management, Team Selling, and Lead Management. And I’ll have a Service Cloud parent with sub-pages for Routing, Channels, Automated Emails, Bots, Escalation Rules, etc. You’ll notice that sometimes I use emojis in my titles too – it helps keep it fun and makes important things standout.

And then you start building out child pages under your parent pages. I like to have a section for each object, and then under the object, more sections for things like automation, page layouts, validation rules, etc.

This keeps everything organized in its own home. Its easily searchable. Its easily scannable. This is a lot of pages for just navigation though, right? What goes on all of these? Well I’m so glad you asked!

Rollup Your Child Pages Using Macros

As Salesforce junkies, we love rollups. We understand the value and the need! And with documentation it’s no different. I don’t want to have to click into 90 different pages to see what’s going on, I should be able to take a quick look. Using the Page Properties macro on each child page, we can create a Page Properties Report macro on the parent and see all of the children in one place.

Here’s an example of the type of information that I like to see on these pages. The name of the process, the API version, who built it, when it was last modified, what type of trigger and when it fires, and the object its on.

Use Page Templates to Standardize

Confluence gives you dozens of templates to choose from out of the box, all developed by teams who do documentation better than me. Use them! I almost always start from a template and then edit it to meet my needs. Once I have a page how I like it, I save it as my own custom template so that I can use it over and over. This is my go-to header for all of my documentation:

You’ve got your page title, an overview section where you can add a summary of what the page is about, and a related table to callout key stakeholders or data like the API version or last modified date. To create this, I use the Layouts macro and choose the large left panel with right sidebar. Inside of each of the layout sections, I add a table. On the left side, I only use one row and column from the table to use as a header. I usually always keep more rows in the right panel, and they are usually the same on each page. You can add some color by changing the cell background color, or do like I do and add emoji! I 💙 emoji.

Call Out Important Things With Macros

Maybe you’re starting to see a common theme here… but I use a lot of macros. They are truly what makes Confluence so great. You know, besides being totally connected to your ticketing system in Jira 😉. So what macros do I use to call out information? Well, I use the status macro a lot for color coding keywords or values in a table.

Another great way to call out information is with the Info, Note, Success, Warning, and Error macros. These create a colored component for you. So like the Error macro creates a red box for you, the Note macro is purple, the Success macro is green… you get it. Use these to draw attention, but use them sparingly so that people actually look at them. Here’s an example of all of them:

Link Pages and Issues Together

I said it before and I’ll say it again, the bonus of Confluence is that its completely integrated with Jira. If you add a link to an Issue on your Confluence page, it adds your Confluence page to your Jira Issue. I recommend as much linking as makes sense for you. This also helps build your culture of documentation though – if I go to an Issue and see a Confluence page listed there, I’ll probably go read it. And I’ll update it. Or create another one and link that to my related Issue. And so on. You can also link Confluence pages together by simply adding a link to the page you want to connect. You can also add Tags for easy searching and navigation. Adding your Confluence pages directly to your Issues also helps you with searchability for later on. Maybe you don’t remember the page name or what section you put it in, but you remember something searchable about the Issue it was related to and if you search that, boom there’s your page.

I Could Go On And On And On And On And On

Literally. I could go on and on and on about documentation, but my biggest tip? Just do it! When I start a new task or a new project, the first thing I do is create my Confluence pages. And then I use those pages to organize my brainstorming, my meeting notes, and any actual artifacts that get created like process documentation or diagrams. Did I mention yet that there’s a macro for diagrams? There are built-in macros that embed Draw.io or Lucid Chart diagrams directly into your page. And they’re live! You can edit them from the page! You can also embed Trello boards! 🙌 There are so many ways to use and customize the pages… but the most important thing is to create the pages, use the pages, and encourage others to do the same.