A HOW-TO Guide Recipe

Recently, the Confluence Guru made a call to action for Confluence templates. Similar to Bill Arconati's request, the desire is to collate templates for the upcoming release of Confluence 3.2, which will feature bundled templates and a new template marketplace. Much like my recent post where I provided a meeting notes recipe, I'm happy to share some of the knowledge I've gained at my company for the benefit of others. So, here's a HOW-TO Guide recipe for Confluence.

People use enterprise wikis for a lot of things, such as letting project teams collaborate or creating product documentation. However, across any organization there are always policies and procedures that need to be followed to accomplish things. There's a process for filling out a timesheet, requesting vacation time, or setting up VPN client software. Sometimes in an organization, these are well-documented and easy to find. Usually, however, they're not, requiring you to go ask Bob in Accounting or Christine in Human Resources how to perform a task. That is, if you're lucky to know who to ask. Often, you'll jump from person to person until you figure it out (or possibly not!).

This is where a wiki can come in handy. You can use it to help organize these step-by-step procedures in a common location and keep things up to date. Having them stored in a common place means even your newest employees will know where to go to get answers to questions they have.

At my company, this is the HOW-TO Space. The HOW-TO space features a single home page that indexes and organizes HOW-TO Guides. From that home page, you can also add a new HOW-TO Guide or Request a new HOW-TO Guide. When you add a new HOW-TO Guide, we use the following template:

Name:

HOW-TO

Description:

A General Purpose HOW-TO Guide

Template Content:

{section}
{column:width=50%}
{panel:title=Table of Contents|borderStyle=solid}
{toc}
{panel}
{column}
{column}
{panel:title=Purpose|borderStyle=solid}
{excerpt}
This section should provide the overall purpose of the HOW-TO Guide. (e.g. intended audience, lesson)
{excerpt}
{panel}
{column}
{section}

h1. Requirements
* This short section should outline the requirements of the reader to use the guide.

h1. Instructions
# This section provides step-by-step instructions for the reader to follow to perform the particular act described in the HOW-TO.

h1. Tips & Warnings
* List any particular common difficulties that the reader may come across

h1. Related
* Link to any related HOW-TOs or External Links

Labels:

how-to

Let's do a little walkthrough of this template. First, we pop in a nice table of contents at the top. Next, we provide a purpose of the HOW-TO, such as "This HOW-TO will inform full-time employees how to fill out their timesheet" which will also be the excerpt if we ever include it in another page. Next, it's a good idea to provide a set of requirements, essentially prerequisites that the user should have either done before or have at-hand (e.g., have an account with the timekeeping system). Now comes the meat, a set of instructions that go through a step-by-step process. You can then follow this up with any tips or warnings, as any process is likely to have. Finally, finish things up with a set of related HOW-TOs or other resources that might come in handy. You can replace "Related" with either the {related-labels} or {contentbylabel} macro to dynamically generate this piece. Or, you can actually use my own user macro, the {related-content} macro, which combines them both. If you're not a fan of user macros, I'm currently in the process of turning {related-content} into a full-fledged plugin.

So there ya go, a nifty little recipe for creating HOW-TOs. It's become really useful at my own company and likely to do well at yours.

You can even go so far as to create a HOW-TO on HOW-TO Write a HOW-TO!

Do you have a similar space or template at your company? Share how you document policies and procedures in your organization in the comments!