FLARE SINGLE-SOURCING: MY TEN BEST PRACTICES
By Chris Sullivan
This webinar is now over. A recording is available here. Webinar Q&As available here.
Necessity is the mother of invention? I say it’s laziness. The first time I had to duplicate content from printed manuals over to an online help system, I started searching for a way to single-source documentation. I tried FrameMaker with WebWorks with poor results. I tried RoboHelp with MS Word output. Good results but tedious reformatting. Finally, Flare arrived with its Blaze integration to create high-quality MS Word documents from online help content. I still have to reformat the output on the backend some, but the effort requires an hour or two instead of several days.
To help feed the sloth in you as well, below are my ten best practices for single-sourcing with Flare.
- Start small.
- Learn to chunk your information into distinct topics.
- Introduce complexity only when you need to.
- Learn to think of your 'Content' folders as source material for multiple deliverables.
- Your TOCs are your deliverables; build a separate definition for each.
- Try to limit your Targets.
- Build conditions for your media.
- Troubleshoot page layouts.
- Sell single-sourcing on the merits of cost-savings.
- Sell single-sourcing on the merits of customer satisfaction.
Find a project that is self-contained, and then try single-sourcing just this one project to see how it goes. Build an online help system and a print guide from the same content. Not only will this help reduce your risk, it will allow you to ease into the complexity of single-sourcing.
Most companies now write task-based (example: ‘How to…’) and/or panel-level content. If you tend to think of your content in chapters, books, and multiple procedures, you will have trouble single-sourcing with Flare. Each help topic is a drag-and-drop object that you can reuse across deliverables.
Take some time writing out the various user roles you need to address as your audience, and think about which chunks of content (topics) you might use for each. If you haven’t done so already, it’s worth the time to stub out some bullet points of the tasks each type of user might want to achieve with the product you’re documenting. Once you have these lists, you will start to see the crossover possibilities between topics (i.e., content your can reuse as single-source).
For example, don't try to maintain multiple CSS style sheets; instead, develop one and use it across deliverables. You will need to apply it to your various targets, and you don’t want to have to try to remember all of various combinations.
With other products, your repository is/was very much a snapshot of your deliverable, so you would build a new project for each one. To get the most out of Flare, learn to get comfortable co-mingling content that is typically unrelated. Placing everything into one project can be a paradigm shift for new Flare users, but it can be incredibly valuable to your teams and to other teams across the company (should you decide to share).
When you crack open the ‘TOC’ folder in the Project Organizer, you should have a list of every deliverable being output from this Flare project. For example, you should see all of your online help systems, all of your print (or PDF) documents, all of the documents related to other teams across the company (should you decide to share).
Since you can see your deliverables represented in your list of TOCs, learn to swap out TOCs for multiple non-print Targets on the fly to avoid maintaining too many Targets. However, consider building a separate Target for each print deliverable since the number of variables tends to increase for print (page layouts, for example).
As a general rule, your conditions are your media (print, online help, etc.); unless your topics are exclusive to a particular media, you must create and mark conditions for exclusions. With our project, we exclude ‘print only’ conditions, while topics that float both ways (print and non-print) receive both conditional tags. Topics that are online only (the vast majority of our content) don’t receive any condition tag at all.
Because of the number of embedded variables, style conversions, proxies, and so forth, print layouts can take a great deal of time to perfect. You will encounter problems; you will become frustrated; you will spend a lot of time on these. Be prepared, and allow time in your project plans and estimates.
Any large undertaking requires justification—to yourself, your boss, and to your stakeholders. Find a way to show hard dollar savings for your efforts. I’ve included the cost-savings calculator I used to get buy-in on my Flare conversion; feel free to adopt it.
Reusing content allowed us to skip an entire step—the Technical Review—since the single-sourced content was already reviewed for technical accuracy in the previous project.
You should also be prepared to justify the undertaking to your customers. Having your content in one central location allows you to make corrections, updates, and additions more quickly. And if you can spread your content to other groups (should you decide to share) in your company, your feedback cycle just gets tighter and tighter.
For example, we provide content for our Training guides, and our trainers get direct customer feedback during training sessions. I hope to expand the reach of our content further to Sales Engineers, and possibly to our Marketing team as well.
Keep separate directories for each contributing group, such as a ‘Training Documents’ folder, and supply the contributors with a copy of Flare to do whatever he/she wants with this folder in terms of content, conditions, etc. Just don’t allow contributors to touch anything else (except his/her TOCs and Targets).
Conclusion
Embracing your inner sloth has its advantages, particularly during tough economic times like we have now. Cost-savings is always a good idea and a strong selling point. Likewise, increased customer satisfaction can only help with job security (stay tuned for my notes on Feedback Server, which we’ve introduced with our upcoming release of CallXpress 8.1). But maybe the most powerful aspect to single-sourcing is its political strength: you can become the content repository for multiple groups. We have completely ditched the idea of implementing a Content Management System for our documentation (minimum savings of $40K, based on the quotes we received). Flare gives us almost all of the functionality we wanted from a CMS (those on the low-end anyway), and it comes standard with the product. I can only imagine how much more we’ll get out of the Flare once MadCap completes their integration with Sharepoint.
Currently Director of Technical Communication and Social Media for AVST, Chris Sullivan has over a decade of training and documentation experience crossing three vertical industries: telecommunications, medical software, and supply chain. He has successfully morphed the training departments for three companies from strictly in-person to e-learning, and he has single-sourced the documentation sets of two companies, saving hundreds of thousands of dollars in redundant effort. His latest endeavor is to increase the voice of the customer through social media.
The majority of our content will come from users just like you. If you would like to become a contributing writer for a future MadNewz article, please email madnewz@madcapsoftware.com.