Content Reuse Strategy in Confluence: Write Better Docs in Less Time
Comment
Content Reuse Strategy in Confluence: Write Better Docs in Less Time
Content reuse helps technical writers author high quality documentation faster and facilitates updates and translation of content. In this post, we explore why you need a content reuse strategy, and share our best practices on how to get started with content reuse using tools that Confluence offers out of the box.
The What and Why of Content Reuse
Content reuse is the practice of reusing existing content elements as part of creating a new document. The goal is to display reusable content in the document without it actually residing within said document. Though most reusable content is text-based, any form of content such as images, charts, or videos can be reused.
Most organizations already reuse content wherever possible in order to avoid the inconvenience of rewriting content snippets like product descriptions or duplicating files or assets. However, most don’t know that they can benefit immensely by avoiding the copy-paste method and introducing a content reuse strategy to their documentation process instead. So why is this strategy better than copy-pasting?
- Easy updates: Reused content can be managed centrally from one place, making it unnecessary to track down all pages it was reused on, which can be very time consuming.
- Content consistency: Reused content appears everywhere in exactly the same form, avoiding inconsistencies or even contradictions, which can happen easily if different content occurrences are updated manually and separately.
- Increased efficiency: Approaching content reuse systematically eliminates the time spent replicating content you didn't know existed or searching for that one bit of content you know is out there somewhere.
- Reduced redundancy: Every reused piece is only stored in one place and does not occupy extra space unnecessarily.
- Cost-effective translation: Reusing content substantially reduces translation costs as the content only needs to be translated once. This is especially true if translation memory systems are in use, where even slightly altered copy-pasted snippets may not be recognized as already translated.
Content Reuse Tools in Confluence
Confluence offers three tools for content reuse out of the box:
Insert files and images lets you search for attached files on other pages to display them on your current page without duplicating them.
The Include Page macro displays the entire content of one Confluence page on another. Any changes to the original page are automatically reflected wherever it is included.
The Excerpt Include macro works in the same way as the Include Page macro, but only displays an excerpt of the selected page. This excerpt must first be defined on the source page using the Excerpt macro.
Our Best Practices for Content Reuse in Confluence
- Create a Library for Reusable Content: As mentioned above, one of the main benefits of content reuse is the ability to store all of your reusable content in one place and make it readily available for everyone. At K15t, we create a top level page and keep a well structured tree of child pages to manage all of our reusable content. For better visibility, we use a leading underscore in every page name, like '_Includes' or '_ReusableContent '.
Create a Naming Convention: To easily find and embed these pages in your documentation using the Include Page macro, we recommend using a hierarchical naming convention within your include library. The search bar in the dialog box of the Include Page macro only displays the first 30 characters of a page title, so keep the prefixes short to make them easily searchable.
- Consolidate Your Building Blocks: Reusable pages can contain text snippets of any length as well as an image or any other asset. We recommend creating a new page for every single attachment and splitting long text snippets into smaller ones on their own pages whenever it makes sense. Doing this lets you use your entire include library with only the Include Page macro, leaving you with a simpler reuse strategy without sacrificing any of the capabilities.
- Use Page Properties to Organize: Adding a hidden Page Properties macro on your reusable pages and a Page Property Report on the top page of your library allows you to sort pages by their properties. These properties can be anything from file type to creation date and help you finding the right piece of content for reuse. Make sure to include the macro below the content to prevent any unwanted blank paragraphs from being inserted.
- Don't Try Too Hard: Not every piece of content is reusable and not every document must include reused content. Trying too hard to make a snippet reusable can lead to creating very generic elements which end up lacking precision. Likewise, trying too hard to include an existing snippet might compromise the quality of the final document. In these cases, it's better to invest the time to write original content or create a derivative.
Advanced Content Reuse
The above tips will get you started with content reuse in Confluence, but these are only the tip of the iceberg. If you want to get the most out of content reuse, Scroll Versions offers you the enhanced Include+ macro along with version and variant management, all of which add leverage to your content reuse strategy.
Are you a Confluence Cloud user? Take a look at Scroll Documents instead →
