Reusing content confidently — our work with Meridian Energy and MadCap Flare

Emily Cotlier | October 2, 2018

Meridian Energy is a leading power company in New Zealand that generates power from only 100% renewable sources: hydroelectricity and wind farms.

Nat Janke-Gilman, Technical Writer in Wind Engineering at Meridian, contacted Write about a very different documentation project. Meridian was updating their safe work documentation for wind turbine maintenance at their wind farms. As part of this, they were converting their documentation to use the content management system MadCap Flare.

Write is one of the few communications groups using MadCap Flare in New Zealand. Meridian came to us to help them format, launch, and clarify their MadCap project.

MadCap Flare helps you reuse content

MadCap Flare is a single-sourcing tool. It allows you to reuse information and gives you a range of print and online outputs. Using MadCap Flare’s single-source features helps you cut down on inconsistencies and update your documents more quickly and efficiently.

Authors use Flare to split their documentation into sections or chapters called topics. Within topics, Flare allows you to subdivide your content into smaller components.

• Variables: reusable, brief, non-formatted text, such as values, terms, or phrases.
• Snippets: reusable, formatted, repeatedly used pieces of information, such as text, tables, or images.
• Condition tags: these markers are used as switches to include or exclude content, or to switch between different versions of the same piece of content for different outputs.

You then assemble documents from these topics and components for your audience and distribution methods, such as print or online output.

Meridian’s work procedures must be accurate and consistent to keep people safe. They achieve this in Flare by using variables, snippets, and condition tags to generate documents from a pool of shared components. Snippets ensure that important reused sections of content are always aligned across multiple documents. Condition tags allow shared components to appear differently for similar-but-different outputs. And variables are a way to control document-specific elements like titles, filenames, and version numbers.

Write and Meridian share MadCap Flare’s full potential

For this project, Meridian had a large set of short documents called Approved Written Procedures for four different wind farms. Many of these documents had content overlap, reusing similar sections. Whenever a set of steps was updated, the changes could apply to dozens or even hundreds of related documents. This was a perfect set of documents to benefit from Flare.

At Write, we’re experienced MadCap Flare users. We provide both MadCap training and support, and we were pleased to support Meridian’s good practices. We set up their main MadCap project. This included:

• recommendations to support the project over the long term
• customised coding to format the look and feel, for example, creating text linked with images for electrical safety warnings
• information architecture, page layouts, and templates for stable, readable content.

First, we set up a large library of reusable content for the Meridian audience. After learning about wind energy technology, we then created MadCap snippets. We applied conditions to the snippets to specify content for different turbine types and procedures.

We used the recently launched MadCap Central function to have several people working on the project at the same time. MadCap Central provides file sharing and management, even task sharing and calendars. Meridian was able to see our progress daily.

Throughout the project, we applied plain language using Meridian’s style and made suggestions to improve usability. Much of the content used plain language already, thanks to Meridian’s focus on safety and reducing human error.

The result: print content today, online content tomorrow

We built a MadCap Flare project for Meridian’s Approved Written Procedures. We had over 200 snippets configured to create over 100 documents. Some snippets are included in every document, while others appear in only a handful of documents. The pool of reusable content allows new documents to be created by plugging together existing components, then setting a handful of variables and condition tags. If procedures need to be updated in the future, a snippet can be edited and then all the related documents rebuilt automatically. This is an elegant, reliable way to manage shared content across a set of related documents, because consistency is built-in. We recommend it!

“Ensuring consistency across a large set of separate Microsoft Word documents used to be a nightmare. Even a small change to our procedures could involve updating dozens of documents. I could be half-way through making those changes when some other improvement came along. The result was a set of documents which were eternally out of date, a backlog of required changes, and frustrated users. For a set of safety procedures, this was unacceptable.

“It was great to have Write’s help to get up and running with Flare. I didn’t have the resources to do this alone, and Madcap Flare’s single-source approach requires special expertise that most writers don’t have.

“Another advantage of Flare is the ability to generate different output formats from the same content. In the future we want to shift from paper-based procedures to responsive content on phones or tablets. Migrating our procedures into Flare was an important first step in that direction.”

— Nat Janke-Gilman, Meridian Energy