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

[Chris Ridgeway]

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!

[Ryan Goodwin · Accepted solution]

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!

[Chris Ridgeway]

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!