Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
© Ugur Akinci
Here are some good advice from MadCap about the best way to go about shifting from a non-structured to a single sourcing platform:
1) Select a small pilot project to test out your favorite structured authoring tool. Get comfortable with what you’re doing at a small scale first before ratcheting up your operation.
2) Identify chunks of information that you can use as independent TOPICS. This would require a serious effort to go through all your legacy documents and identify those text blocks that you have used over and over again through the years. For example, a text string such as “Click OK to close the dialog box” is one such modular “topic” that needs to be written only once and used many times. This would decrease the writing load on technical writers by encouraging them to concentrate only on what is genuinely new in a document and not those “repeatable parts”.
3) Get used to thinking of topic files only as storage bins and not as a part of the sequential “book structure.” As you know in programs like (unstructured FrameMaker), the position of a content file in the book file determines how the final output will look. Not so in MadCap Flare. You can take a topic and stick it anywhere you like in the final deliverable regardless of its “position” in the content tree-view.
4) Watch your conditions. On the one hand you need to develop different conditions to toggle certain topics on and off, depending on the publishing platform (print PDF, online help, mobile, etc.). But you should also try to keep things as simple as possible by having as few conditions as possible. The eternal rule of parsimony (also known as Ockham’s Razor in philosophy) rules here as well. Thou shalt not proliferate the number of components in a system (ANY system) beyond what is absolutely needed. That’s where “art” is introduced to the “science” of single sourcing. No matter how good the software gets, we always have to make the final “judgment call” to get things right.
5) Test your page layouts in advance. Most top-notch single sourcing platforms do provide a simulated environment that helps you to see how your final output would look like online, on an iPad, etc.
6) Sell the economic benefits of structured authoring to your management and the end users. With management, lower production and deployment costs are the key. With the end users, availability, frequent updating, social media “crowd-sourcing” opportunity, and lower ownership and maintenance cost should be emphasized.
For upcoming MadCap webinars:
Also: 10 tips for importing FrameMaker content into Flare