3 Items
Define Topic Types with Templates
Steffen Burzlaff
Use templates in Confluence to create topic guidelines without restricting the writer's imagination.
Generally, there are a few different types of topics, and each helps users with a different need:
Concept—Discover a new concept
Task—Learn how to do something
Reference—Locate a specific piece of information
Troubleshooting—Work through an issue
Confluence includes tools like instructional text, template variables, and macros to help you create templates. Think of a template as a recipe for creating a topic. Sometimes you stick to the recipe completely, but sometimes you improvise on the original for a slight twist. To get writers started, your templates should include guidelines for creating a topic of the given type.
Learn more about Confluence page templates.
Instructional Text
Instructional text is placeholder content in a template, and is only visible while you're editing the page. You can add instructional text to give writers guidance as they begin. Once they get the idea, it's easy for writers to delete instructional text and replace it with their own content.
When writing instructional text, remember that it will be seen every time a writer creates a new topic. Here are a few tips when writing instructional text:
Place it exactly where you'd expect to find the content it's describing
Keep it brief, but informative
Be helpful, not restrictive
To add helpful links for your writers within your template, avoid adding them as instructional text. Instead, place the links in a Panel macro with a title like: "Remove Me". This way your team can get started quickly and then remove the panel when they're done writing.
Learn more about instructional text in Confluence.
Template Variables
To speed up page creation from a template, you can use variables. When adding variables in a template, a form is added to the top of the page where writers will later input data for each variable. You can insert a variable within the template content, even in multiple places.
Variables are great for bringing consistency to new pages quickly. For example, you may have sections in your concept topic template titled "How [feature name] Works" and "Things to Keep in Mind When Using [feature name]". Using the variable $featureName, writers can write the feature name once in the template variable form and it will be reflected in the rest of the page.
Learn more about template variables in Confluence.
Template Formatting Suggestions
As you create templates for different topic types, there are a few guidelines we recommend. A concept topic template might include:
An excerpt macro for the short description
A table of contents macro for quick navigation
Sub sections you recommend adding
Filler text explaining what type of content should be written
A task topic template might include:
An excerpt macro for the short description
A numbered list for the steps to complete that task
A reference topic template might include:
An excerpt macro for the short description
Filler text explaining what type of content to write
A troubleshooting topic template might include:
An excerpt macro for the short description
A section for the description of the possible cause of the issue
A numbered list for the steps to remedy the issue
