About this article
By Desiree Conceicao, published July 13th, 2016
Harness your organization's collective knowledge
How-to articles let you share valuable knowledge across your organization in a way that requires little time or effort. They're useful for creating consistency, formalizing processes that people might be unsure of, and helping new team members be more productive right off the bat.
Confluence comes with a default how-to article template, which you can customize for each space to make writing your how-tos as quick and easy as possible. And, when you first create a how-to article, Confluence automatically creates an index page in your space sidebar so you can find all the how-to articles within a space in one place - where they can be ordered by title, creator, or date modified.
To use the how-to article template, choose the Createbutton from the sidebar, then select How-to article.
1. Choose a specific title
What are you teaching people to do? Choose a descriptive title that matches up with what your users are likely to search for when they want to solve that problem. If you've got a long list of how-to articles, naming them all "How-to do whatever" can make your list hard to scan. Instead, you can also make use of variations on this, like "How do I get more statistics from Confluence?" or "Capturing HTTP traffic using Wireshark or Fiddler".
2. Add some labels
Adding labels to your articles makes them easier to find and organize. Users can search by label, or use a Content by Label macro to generate a list of all the content tagged with a certain label. The how-to article template automatically adds a 'kb-how-to-article' label to your document, but you can also label your article with the topics it covers or with any other categories that it falls into. There is no limit to the number of labels you can add, or to the label combinations you can search for.
3. Write an introductory overview
Why do people want to do whatever you're teaching them, and in what situations? For example, if you were writing a How to clean the office dishwasher article you could explain that this needs to be done every few weeks to prevent the clean dishes from starting to smell like sewage water. This helps explain the value of whatever you're teaching and lets your users know when it is or isn't appropriate to do it.
4. List anything they might need or should watch out for
Does your user need to have a specific piece of software installed? Do they need any special permissions? Will they require a wrench to do this job? You can use a Tip or Info macro to highlight this information.
If this how-to is conditional, or if there's anything that might prevent them from being able to use it, let them know with a Warning macro. This could be, for example, letting your audience know that a piece of software you're providing installation instructions for is not supported on very old versions of Windows.
5. List the steps
Go through each step using clear, simple language.
- If there are a lot of steps, add a Table of Contents macro to your page, so it's easier to navigate.
- Format your page so that it's easy to read. If each step is quite long, choose a brief heading for each step, then put the rest of the information in a paragraph underneath it. Where applicable, use bullet points instead of dense paragraphs.
- Break each step into its components. Your users might not find everything as obvious as you do, and it helps prevent ambiguity and mistakes. Instead of saying "Check who the space admin is", say "Choose Spaces > Space directory in the Confluence header, then choose the Space Details icon beside a space. The space admin will be listed there."
- Avoid jargon if possible, but if you must use it, try either defining it in a Panel macro or Info macro, or hyperlinking those terms to another page with more information about them.
- Use screenshots, diagrams and visuals – it makes your article easier to read and can be used to make some of your steps clearer.
6. Related information or tips
Use the Panel macro at the bottom of the page to share any additional information your user might find useful. For example, on a page about how to set up your printer, you might want to tell them how often they should refill the paper tray, or let them know that they can print double sided to reduce paper waste.
7. Link to related content
The Content by Label macro at the bottom of the template automatically pulls a list of articles by label. Click edit on the macro to choose what labels it uses and it'll automatically update the list for you every time you add that label to a piece of content. This means that if you're writing an article about how to set up your printer, for example, you can also have links on your page to "How to change the printer's ink cartridges" or "How to fix a paper jam".
- If you use any JIRA application – Add a JIRA Issues macro to your troubleshooting article to provide quick access to known issues. This has the added advantage of automatically updating when an issue is resolved or its status changes.
- If you use Questions for Confluence – add a Questions List macro to troubleshooting articles, to highlight the top questions with the same topic as the article, and an Ask a Question button to the knowledge base homepage.
When you create your first how-to article in Confluence you'll notice a page properties panel at the bottom of the page. The Page Properties macro works in conjunction with the Page Properties Report macro to let you create a summary page that pulls in information from multiple pages. In this case you could use the Page Properties Report macro to create one page for all the how-to articles across your organization.
8. User test
Check that your how-to article is clear enough by user testing it on someone outside your department. If they get confused or find it difficult to do whatever you're teaching them, you may need to simplify some of your steps further or provide additional information.
9. Follow-up after publishing
Once you've published your article and shared it with the rest of your team, users can use inline comments if they need further clarification or assistance with any of the information you've shared. When you've dealt with the inline comment, click Resolve and it'll disappear from the page. You can always find resolved comments again in the more actions menuto help you track what your readers need more help with.
At a glance: what did you just learn?
- How-to Article template: It does most of the work for you. Follow the page outline, and fill in content that makes sense for your specific requirement.
- How-to Article Index: Once you've created a few requirements pages, you can see all the high level details at a glance on an index page that Confluence automatically creates when you use the template.
- Page Properties macro: This macro makes it possible to create a reporting page across all your how-to articles. When using the template it will be included on your page.
- Content by Label macro : This is used to display lists of pages, blog posts or attachments that have particular labels.
- Table of contents macro : Creates a table of contents based on the page headings.
- Info, Tip, Note and Warning macros : Allows you to highlight important information.
- JIRA Issues macro : Create and display dynamically updating JIRA issues on your Confluence page.
- Customizing templates: You can edit any of the templates that come included in Confluence to fit your specific workflow.
Hungry for more?
Watch the blogs in this space to get notified when new tips articles like this are posted.