For this reason, I am a major fan of MadCap Flare. I recommend this extremely robust, customizable Content Management System to all my clients when they need to output a mixture of shared and unique content to multiple audiences. The graphic design capabilities are incredible as well. I’ve replicated gorgeous designs from InDesign in MadCap Flare. And I recommend their Getting Started documentation as the gold standard for what end user documentation should be.
What Makes Outstanding Documentation?
Technical documentation must meet the needs of the audience. The best documentation enhances the user experience and is:
accurate
easy to find
easy to understand
describes the tasks the user must perform
provides solutions to those frustrating problems that make us turn to the documentation in the first place.
What’s Great About the MadCap Flare Documentation?
Text chunking makes the material easy to absorb
Navigation is excellent—easy to understand, with an easy-to-follow tree hierarchy, with concepts organized into task-based sections
Introductory material is provided in both text and video format, and the videos are very appealing and engaging
The language is simple and easy to understand, even when explaining complicated concepts
As a marketing tool, this URL makes a very complex, robust Content Management System seem non-intimidating and easy to use. For users of the software, this is a great starting point for learning basics, and even experts may return to this material for foundational concepts.
As a New York-based technical writer with more than two decades of experience writing for clients in varied industries, in locations from Vancouver to New York to Haiti to Chile, I notice universal themes—pain points that affect all of my clients, whatever their business line or type of documentation.
It’s all about the user experience (UX). If your customers and staff can’t use your product or perform their task, the result is pain and frustration!
Top 5 Technical Writing Pain Points
Here are the top 5 technical documentation pain points:
Obsolete! Existing documentation or procedures are out-of-date
Unclear! Instructions are hard to understand, so staff or customers can’t follow correct procedure
Disorganized! People can’t quickly find the information they need
Incomplete! There are no answers for the particular problem or task
Inconsistent! Procedures or instructions have been updated in one place but not another, leading to conflicting and confusing information
First Aid for Technical Writing Pain Points
Here I’ll tell you how good technical writing documentation addresses these pain points, one by one. Turn your user experience (UX) into satisfaction and delight!
One: From Obsolete to Up-to-the-Minute
Documentation quickly becomes obsolete without a plan for updating
Time takes a toll on any set of documentation, bringing changes that require updates. Consider this when you create your documentation, and use a system that will be easy to update. Of course, that train may have already left the station, in which case you need:
A Content Management System to keep track of all your source documents
A regular update process and schedule
A system for keeping track of changes, whether it’s specialized software or simply an Excel spreadsheet or an internal Wiki.
Two: From Unclear to Crystal
User testing is key to ensure your technical documentation is clear
Unreadability leading to lack of understanding is one of the biggest problems with documentation, and it usually occurs because the person who wrote the documentation knows the subject matter well but is not a skilled writer. Ways to ensure your documentation is crystal clear:
Use a simple writing style aimed at an eighth-grade reader
Explain all jargon and technical terms
Get actual users to follow the instructions and test the procedures – sounds like a no-brainer, right? But few companies actually do this!
Three: From Disorganized to Swiss Precision
Tagged and structured content is as organized as a Swiss candy shop
Disorganized, hard-to-find information is a very common problem, especially with complicated software or procedures that require lengthy documentation. If you have a thick binder of operating procedures or a stack of user guides, chances are, no one will look at them. But even a slender tome won’t help if the user can’t find the information they need.
To make your content findable:
Organize topics with clear titles and headings
Deliver content in a searchable online format so that people can quickly look up the subject
Include alternate search terms in your text or tags, so that people kind find a subject even if they don’t know the exact term that they’re looking for
Organize content by user task, not by the software menu structure.
Four: From Incomplete to Spot-On
Do you have gaps in your documentation?
Identifying gaps in the documentation is tricky, because you don’t know what you don’t know. Here are some sleuthing techniques to discover what’s missing and fill the holes:
Test the software or process rigorously, to find out what areas haven’t been documented
Make a list of all the tasks or procedures your users need to perform and correlate this to the existing content to identify gaps
Try doing the task wrong to find out what trouble-shooting tips your users will need
Again, user-test the documentation and watch where they go wrong, as well as what kinds of information they try to look up, then make sure you give them what they need!
Five: From Inconsistent to Single Source
Consistency is king!
Inconsistency is a problem that often creeps in over time as different people update the documentation set, perhaps making changes in one place but not another, or using different terminology to describe the same thing. Even different writing styles can be confusing to the end reader.
With technical writing, consistency is king! To achieve it:
Develop style and terminology guidelines, and follow them
Keep on track by having an editor or dedicated staff member oversee all updates when you have a team making changes
Use a Content Management System such as MadCap Flare to single source your text, so that a change only needs to be made in one place and it will be automatically updated throughout your documentation set.
A Cure for the Pain
An expert technical writer helps you succeed!
What is your top pain point? Do you need a remedy?
Karen Rempel, technical writing expert, to the rescue!
A good documentation specialist can solve your unique problems and create a set of documentation that meets your user needs and is easy to maintain.
The technical writer is the advocate for your user, and brings a perspective that will help you design documentation that is findable, clear, and easy to follow.
You get what you pay for. If you have a complex project, a product that is complicated to use, or procedures that are difficult to perform correctly, you need an experienced, expert technical writer. Budget for a professional, and you will save money in the long run.
I am pleased to announce a collaboration with California-based Tom Johnson of I’d Rather Be Writing. In 2008, he wrote a definitive review of MadCap Flare v3 that has helped countless technical writers and prospective users of MadCap Flare. Since I had the pleasure of doing a recent MadCap Flare project for BC Hydro in Vancouver, we agreed that I would update his review and add some insights on MadCap Flare 11.
I recently completed a technical writing project for a Vancouver- and Calgary-based client who is a management consultant, program manager, and project manager in IT. Like many consultants, he has worked in a range of industries, and with over three decades’ worth of experience, he faces the challenge of condensing his experience and skills into a 3-page resume targeted to clients in two provinces. What would be a good way to solve this challenge? Enter MadCap Flare.
[Click the graphic to see a larger view that shows the use of condition tags]
Often thought of as an online help authoring tool, MadCap Flare is also a very user-friendly content management system (CMS). It provides a wide range of online and print-based output options (for example, Word, PDF, html). It uses XML as the backbone, making it easy to import source content and play nicely with most of the industry-standard authoring tools on the market today.
I thought that MadCap Flare’s CMS capabilities could help solve my client’s problem by providing a single-source database of skills and experience from which he can output a role- or industry-specific resume with one or two clicks of the mouse. In the words of our beloved Captain Jean-Luc Picard, I made it so.
I imported my friend’s main resume from Word, and then added in content from five other role-specific resumes, with conditional tags indicating which content belonged on which resume or CV. I set up two different style sheets, for two different looks – executive dark blue, and executive brown. I set up variable text for his phone, email, and mailing address, so he can select which of these to use on a given resume for a particular client. Then I created target outputs for nine different resumes. Et voila!
All my client has to do is click Build Primary and then select the resume he wants to generate. But best of all, updating his resume with new experience is a snap. He can use MadCap Flare’s intuitive XML editor to type in new content, then apply conditional tags to specify which resume the content belongs with. Then simply use those same two mouse clicks to generate his new target resume. Beautiful. As you can tell, I am a fan of the Flare!
Of course, MadCap Flare isn’t cheap—a perpetual license is over $1,000 CAD (including tax). But for professionals who are aiming for top-paying consulting jobs, it is a reasonable career investment, and a tax write-off. If you are interested in creating your own database of role-oriented, industry-specific resumes, give me a call and I will be happy to help you.
