documentation style: common formatting macros like info, note, tip

So we're just finally opening up our first Confluence instance out of beta into full release, and our departments are starting to upload content across the site. We are using it for operational knowledge base, some project management, and a more formal manual/documenation set. Probably 30-50 spaces.

We're trying to figure out how much to control in terms of consistency in formatting across the site. One thing I'm noticing right away is that people like the Info, Tip, and Note macros. But they are using them rather inconsistantly. Sometimes info is used for information about the page ("This page is for X") and sometimes it's used inline with content.

I'm looking for comments or examples on best practices on formatting macros across the site. From a reader's usability standpoint, it would be nice if yellow "Note" boxes always meant something similar, for instance.

Questions:

  • Do you use these common formatting macros consistently throughout your site?
  • If so how do you define them?
  • And how do you get users to use them in a consistent manner?
  • Do you have other resources to point to on best practices for consistent formatting in a wiki?

Thanks for input and help!

1 answer

1 accepted

This widget could not be displayed.

Hi Chris,

It's a tough question to address. I think the usage of Confluence will boil down to proper training, but ultimately users will still utilize these things at their discretion.

I would define them by setting up a training space, that then declares how to utilize the specific features you see in the way your organization wants them to be utilized.

As for consistency, this requires curation. For our knowledge base, we use templates that suggest using info macros in certain areas for information additional to steps in resolutions. We are also prompted to delete the info macro if no additional information is necessary. Info should be what we consider a side note, or information in addition that is outside the steps we're asking users to follow. Like a verbal "Oh by the way this is important information or the reason why we're having you perform these steps."

I would recommend that you discuss what these macros should insinuate to your readers, and what the evangelists and power users agree they mean. Then setup a legend/dictionary/training space or a few pages that users can reference to ensure they're keeping in line with company standards.

Hope that helps!

Getting back to this much later, but thanks for the answer above. Yes, this seems to be the solution we have leaned towards: we have a Space just for training/style/best practice, so we've set up some formatting definitions there. Still a challenge to get people to read that stuff. As a relatively small-medium non-profit organization on a 50-user license, we don't have staff to assign to be information curators, and we're learning that can be tough.

Good to know that Atlassian may have the same consistency issues though. It's a trade off for the open system. Thanks!

Suggest an answer

Log in or Sign up to answer
Atlassian Summit 2018

Meet the community IRL

Atlassian Summit is an excellent opportunity for in-person support, training, and networking.

Learn more
Community showcase
Posted 7 hours ago in Teamwork

What teamwork quotes inspire you?

Hey everyone! My name is Natalie and I'm an editor of the Atlassian Blog and I've got a question for you: What's your favorite quote about teamwork?  We've compiled a list here, along with...

17 views 0 4
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you