Highlighted

Have you adopted a style guide for Confluence?

Addy Free Feb 02, 2018

Has your institution adopted a style guide for Confluence as a knowledge base? If so, would be willing to share that style guide with me?

We are a small liberal arts college and implementing for just one office at this time. The plan is to build out an internal knowledge base. Thanks!

1 comment

E. L. Fridge Feb 06, 2018

We don't have a style guide per se, instead we use templates for many things in our KB.  We have a template called a "business process" which contains info about large concepts or ideas on campus.  These usually get created by our admins, and represent the big ticket items that we need to document.  We then have another template for "procedures" that are nested underneath these processes.  Other templates include "system" for documenting a system like email, or a "grouping" template that isn't really for content but can be used to group other documents and provide a page-tree listing.

In our training we show users examples of well documented procedures and help them get started writing their own.  We encourage users to title their procedures with "-ing" words to indicate that it's an action to be done, for example, "Updating program advisor assignments."  The template is set up in such a way that it's got areas for the steps of the procedure and uses the table of content macro on a sidebar.  This, combined with a common space template, usually helps content to be somewhat consistent.  We've got people who watch certain parts of the space and jump in to make comments or propose corrections when something goes wrong.

I hope this gives you an idea of how things are set up here.  It's not a perfect plan, but the beauty of a wiki is that it's a living document that is constantly changing and improving.  Let me know if I can help with more examples or ideas.

Like Addy Free likes this
Addy Free Feb 06, 2018

This is a really useful response. Thank you for taking the time.

I haven't poked around enough yet to look at export/import options, but if there's a way for you to share your templates with me, I'd be glad to hear of ways Macalester could help West Florida sometime. And access to any user or admin documentation you use to train would be grateful received.

Basically anything you want to give, I'll take because it sounds like you've got a good model and I'd like to model our KB on successful implementation in the higher ed space and not try to shoe-horn our instance into another industry's standards.


My email is free@macalester.edu

Brant Schroeder Community Leader Oct 16, 2018

I am also interested in what your templates include.  It would be great if you could post additional information in this post.

E. L. Fridge Oct 16, 2018

Ok, here's some more info.  I'm including a screenshot of one of our templates so you can see an idea of what we're talking about.

All of our templates have a sidebar that uses the table of contents at the top and a page properties macro below that.  

For the main part of the page, we've got an overview section that includes the excerpt macro, so if another page wants to display this text it can do that with the excerpt include macro.

This particular screen shot is from our business procedure template, which documents a step-by-step process for doing something.  In this case we've got a place for the instructions on how to do the procedure.  There are some optional FAQs and Previous/Next Steps where we can answer common questions and send people to other related pages.

At the bottom of each page is a contributors area, where we list out the people who are watching or have worked on a page.  This uses the future macro from the Bob Swift cache plugin to make things render efficiently.

Other similar page templates (not shown here) are the grouping template and the process template.  The grouping template simply has a page tree in the overview section, so it will list all the children of the page.  It's used to add a single entry that will group many related pages together.

The process template provides an overview of a business process at a high level.  Instead of instructions and FAQs, it has a list of procedures and sub-processes.  There is a specific label assigned to this process, so if any procedures that relate to it have that label, they will be shown on the process.  It also will use the HTML include macro (once again inside the cache plugin for efficiency) to pull in related content from an application server that details other systems and automations that may be related to that process.

2018-10-16_15-21-28.png

Like Alexander Bondarev likes this
Brant Schroeder Community Leader Oct 16, 2018

Thanks

Comment

Log in or Sign up to comment