For any organization considering migrating to MadCap Flare, several fundamental design questions should be addressed before starting a project. In an industry as highly regulated as aerospace, making the business case for transitioning from Word to Flare is a challenge. The product is highly regulated by the federal aviation administration (FAA) and by a Global Aerospace Manufacturer. Further, you have to build consensus among stakeholders for adoption of Flare, AND confront the classic argument: “Why change the status quo?”
To succeed, you must guide your stakeholders into a “revolutionary” way of creating documentation: using Flare as the content management system (CMS). I was tasked with creating PDF Targets, based on importing from Word to Flare, and publishing to an Intranet. The following is an overview of how I made the transition to Flare, including the main takeaways from phase one.
1. Make the Business Case & Defend It
First, I met with managers and key stakeholders to determine how (or if) they planned to manage their new digital assets. I discovered that not only did the managers not understand the benefits of a CMS, they didn’t understand that building a CMS with Flare is an investment that yields benefits over time—after a library of digital assets has been established. Therefore, I had to make the case for a CMS using a “single-source,” which gives authors the ability to reuse and repurpose content in the future. I recognized my sales pitch for the CMS was akin to Columbus petitioning King Ferdinand and Queen Isabella. And yes, just like Columbus, I wasn't the first.
It’s seems obvious, but if an organization doesn’t make a plan on how to organize the digital assets, it can cripple a project, or worse, defeat the purpose of using single-sourcing for content management. In my project, though it started small, I recommended:
- Creating a proof of concept/conference room pilot (CRP)
- Setting project review deadlines for CRP deliverables, with at least 5 test deliverables
- Defining the size and what constitutes a “topic”
- Codifying images using an alphanumeric scheme (whose numbers correspond to part numbers in the ERP).
If your organization doesn’t have a plan, I recommend that you meet as soon as possible and make one. Not having a plan can be a liability. Be willing to make a plan, and then change it, based on new insights. For example, when I met with stakeholders, I proposed renaming all the imported graphics by assigning them alphanumeric filenames. The first 3 letters use the Item description; next 3-5 letters used the Item/Part Number, and final two digits are set at “00” (e.g., ACT-221215-10-00.jpg) to allow multiple views of the same part during a product’s manufacture. Revised image filenames provide three major benefits:
- Traceability of digital to physical assets;
- Other writers can search for an image/graphic based on the Item/Part Number (found in an organization’s ERP)
- Other writers who are less knowledgeable can search for an image using an Item’s first three letters.
2. Bridge the Gap: Transition with Templates
Second, I created a simplified template in Word and modified Styles, limiting the number of Styles to about six. My approach: if I created a Word template for several engineers who already used it to write Work Instructions, I would simplify the publishing team’s job when importing from Word to Flare. Thus, the Word Template would serve as a bridge between Word and Flare. In Word, my styles were limited to: Caption, Body Text, Bullets, H1, H2, and Table. Then, for New Topic Styles, I used ONLY the H1 tag in order to subdivide content into manageable topics. And when it came to “Paragraph Style Mapping,” I mapped Styles using the Heading 1 for H1, Heading 2 for H2, and for the rest I simply mapped to “p.(MS Word Style).”
This simplification would limit how many Styles I’d have to manage in the CSS and in the Text Editor, helpful when I needed to edit the XML.
Creating a Word Template with pared down Styles has several benefits. If your user group is accustomed to using Word (and cannot use Flare), creating this template will save you time and undue stress. It will also create a bridge between those who use Word and those who use Flare, thereby allowing a phased transition without “pulling the plug” on using Word.
3. Promote Ownership: Consult Stakeholders Often
Finally, one of the most-overlooked tasks of transitioning is to include stakeholders in the decision-making process. In my project, I proposed an alphanumeric code for renaming images (as mentioned above). However, I also learned a lot from my stakeholders about their preferences. For example, the Departmental Manager was quick to ask how some text would be re-used so the organization could reap the benefits of single-sourcing. In response, I created some reusable topics, coding them as “H2” or Body Text; therefore, these topics could be easily inserted into the TOC, and published in the Target, without the default characteristics of “H1”, which create a whole page in PDF.
The beginning of any journey is critical because it sets the stage for what will follow. I’m reminded of Christopher Columbus’ proposal to Isabella and Ferdinand to get funding for three little ships. With some organizations, you’re asked to guide others in discovering a world they doubt exists. To take your stakeholders on this journey to the “New World,” it’s best to organize a project well, and provide tools, like Word templates, and provide project deadlines and deliverables for management to review. This sets clear expectations and enables the stakeholders to take ownership in the deliverable, which is the best possible outcome in making the business case for MadCap Flare.
