Get hands-on training for JIRA Software, Confluence, and more at Atlassian Summit Europe. Register now ›

Craft it with care. Review it with your Subject Matter Experts. Keep it in a central location and regularly maintain and update it. Re-use it as required. This is the third of a series of posts from Atlassian’s Technical Writing Team focusing on using a wiki for technical writing. The second post in this series discussed how many people still think of a wiki as an unstructured collection of pages, but in fact wikis do support structured content. In this post, I’ll be talking about how to leverage that structure in support of content re-use.

Counting the Benefits

Content used to be king. Now content re-use is king — it’s the ‘killer app’ that saves time and money. Content re-use in a wiki also means you’re still on the same page no matter how individual the contributors, the process or the content.

There are four clear reasons to aim for content reuse. It:

  1. saves time
  2. saves money
  3. provides consistency
  4. helps you repurpose and adapt your content to specialised audiences and needs

Content re-use enables you to focus on crafting libraries of content and then pulling these elements together either on the fly, or to assemble new pages or custom page collections — chapters, training manuals, product feature cards, etc. at need. A wiki provides a good collaborative platform to start your journey towards becoming a content ninja. And Confluence ‘out-of-the-box’ capabilities are a wiki-ninja’s secret weapon.

Users of more conventional technical writing tools are already familiar with the concept of separating content, style, images, and ‘boilerplate text’. Think here of how you design HTML content.

html-design-elements.png

At first glance a wiki may not be your initial choice for content re-use — after all, wikis are all about everyone contributing to the same page and collaborative content creation. But some wikis like Confluence are feature-rich and flexible enough to provide for collaboration and content re-use. Here’s an example scenario:

Your team has developed a series of FAQs for a product re-launch and your marketing team has refreshed the product branding. You’re updating the product documentation and helping develop product training manuals and fact sheets. You’d like to use paragraphs and passages from the FAQs and ensure that the rebranding is visible across the product.

The Speed and Zen of the Content Ninja

The benefit of content re-use means you can use the text in the FAQs as content inclusions elsewhere in your documents, and all of your pages with product images and logos can be quickly updated.

Image Libraries

Your wiki can house all of your images in a central place. As with other technical writing tools, these images can be organised in a separate area. To create an image library, instead of attaching your images to each page, you can attach your images to a single page and then include them in other pages. This means the images are collected, maintained, and referenced from a central repository.

Image Library

Your entire image library can also be downloaded as a single zip file for developer or marketing review and update as required.

Download All Attachments

See also:

Attachments Library

Just like images, you can create an attachments library for PDFs, Excel documents, and other files you reference regularly.

See also:

Boiler Plate Content

Even in a wiki, where you regularly use the same content in different pages, you can apply the principles of ‘boiler plate’ text. Copyright statements, repeated instructions, or glossary items all require consistency of wording and terminology. You can reference this repeated content from your inclusions library to ensure readers are always presented with a consistent message.

Think of your inclusions library as just that — a library of content you can select from as required. This means you can quickly assemble pages when you need them. Perfect for working in an agile environment. Perfect for cross-functional teams. Perfect for creating customised resources. And all of this done with speed and zen.

Confluence’s Include and Excerpt Include macros help you become that content ninja.

Glossary or FAQ Items

Glossary or FAQ items are good examples of content re-use. For example: your team has devoted a lot of collaborative effort to creating an extensive list of FAQs and you’d like to use this information in training manuals.

Here’s an example FAQ:

frequently-asked-question.png

Here’s your new page, which includes this FAQ:

faq-include.png

How we created the page through content re-use:

content-reuse.png

Meaningful Pathways

Even with our best content strategy in place, readers will get lost. It’s the nature of information-seeking. Content re-use provides another way for us to help them find their way. Content ‘re-use’ is also about enabling meaningful pathways to content. Think here of visual cues such as headings, and lists that signal text hierarchy. This helps provide readers with a mental model of the structure of documentation, which can be almost as effective on the page as a Table of Contents or Index. Repeated placeholders or anchor-points such as “On this page”, “Why would I do this?”, or “Related Topics” can also help readers navigate and make best use of your carefully crafted text.

Channelling the epic talents of Homer, Sarah Maddox, one of Atlassian’s Technical Writers, has written a post dedicated to this aspect of content re-use: What Homer Knew about Technical Writing.

See also:

What’s Next?

So now you know how to structure content for re-use using a wiki, where to from here? In the next post of this series, Rosie Jameson will be discussing how you can manage the release cycle by creating archives of your documentation before updating and publishing new versions. In a subsequent blog, we’ll be showing you how a wiki can support single source publishing.

Start using a wiki for technical writing for $10

With perpetual, full-featured licenses starting at $10 for 10 users, Confluence is an ideal solution for your technical documentation needs.

All Confluence licenses allow for unlimited anonymous users.

get_started_button.png

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now