This guest post was written by Scott DeLoach, the founder of ClickStart, a company that specializes in MadCap Flare consulting and training. Scott is a certified Flare instructor and consultant, the manager of MadCap Software’s certification program, and the author of MadCap Flare: The Definitive Guide.

Drafting effective documentation involves much more than just good writing — it calls for proper project management. This becomes increasingly important as you look to increase workloads for your team in hopes of delivering more quality documentation to your customers.

Of course today’s technical documentation software is designed with the technical writer in mind. Technical writing software such as MadCap Flare offers a number of different capabilities that can make the development process for your technical writing a breeze.

In this blog post, I will share tips for managing technical documentation projects, particularly in MadCap Flare. I’ve focused the tips on four common project management challenges:

  • Tracking and planning revisions
  • Single sourcing
  • Team authoring
  • Troubleshooting

I also recommend conducting a yearly project “checkup" to ensure everything stays on track. Keep reading below to learn everything you need to know about getting the most out of your technical writing software.

Tracking and Planning Revisions

Flare provides several features for tracking revisions:

  • Tracked changes
  • Annotations
  • File tags

Tracked Changes

With Flare in particular, you can turn track changes on or off within a file, and you can accept or reject each change or all changes within a file (Review > Track Changes). Before you start tracking changes, you should make sure Flare is set to use your correct name and initials (Review > Review Options) for tracked changes. You can also specify whether the tracked changes appear inline or as balloons in Flare’s editor and whether they are marked with a revision bar within your technical document. When I work with a team, we usually set Flare to use a different color for each team member’s tracked changes. The color coding provides another way to tell who made the change. However, the different colors can be distracting if you have several authors and multiple tracked changes.

There are two easy mistakes to make with tracked changes: not clearly understanding how they work and accidentally hiding the tracked changes. Tracked changes allow you to make changes to a file that will not be included when you build a target. For example, you can track your changes and accept them once the changes have been approved. If you send a file to a reviewer who is using MadCap Central or MadCap Contributor, they will see the tracked changes. They can even add their own tracked changes. If you must send your reviewer a PDF or Word document, you can still include the tracked changes in your technical document. Just select Preserve Tracked Changes on the Advanced tab in your target.

If you build a target and the content does not include your changes, you probably have tracked changes on but hidden in the editor. In the Review menu, Track Changes turns tracked changes on and off. The Changes checkbox shows and hides the tracked changes. If Track Changes is on, you most likely also want to check the Changes checkbox so you can see them.

Annotations

Annotations (Review > Insert Annotations) can be used to add notes or comments. I often use annotations to mark content I plan to revise or delete. Many teams use formatting, such as a yellow background or strikethrough, and/or condition tags to mark content that should be revised or deleted. Although this approach can seem easy to use, it’s almost always less useful than using annotations. Annotations are not included when you build a target, so you don’t have to worry about users seeing them.

If you use formatting or condition tags for your project management notes, you will most likely need to hide them in your outputs. That’s more difficult to set up and maintain, and the formatting can end up being distracting in the Flare editor. Another advantage of using annotations is that you can use Flare’s Files with Annotations report to find all the annotations in a project (Analysis > More Reports > Files with Annotations). There’s also a Files with Tracked Changes report to find all tracked changes (Analysis > More Reports > Files with Changes).

File Tags

Unlike tracked changes and annotations, file tags are assigned to an entire file. They can be used to track higher-level revisions, such as topics that should be modified as part of a sprint or release or files that you plan to delete. The File List (View > File List) contains a column for each file tag, and you can sort the files based on their assigned file tag. You can also use the Used File Tags report (Analysis > Used Items > Used File Tags) to review a list of files that have a file tag.

Single-Sourcing

Flare’s primary single-sourcing features include condition tags, variables, and snippets. These three features can drastically increase efficiency. However, to successfully single-source content, you must:

  • plan how you will use conditions, variables, and snippets
  • implement them correctly
  • ensure everyone on the team understands how (and why) to use the conditions, variables, and snippets
  • periodically review and adjust your single sourcing plan and approach

The first step is to identify duplicated content. I use Flare Snippet Suggestions, Variable Suggestions, Frequent Segments, and Similar Segments reports (Analysis > Suggestions) to find and convert duplicated content to variables and snippets. I also recommend enabling the variable and snippet auto suggestion features (File > Options). The auto suggestion features will automatically remind you to use a variable or snippet if the content you type matches an existing variable or snippet. The auto suggestion features are especially useful for large teams since they help notify everyone if there is a new variable or snippet in the project.

I create a condition tag matrix to identify the condition tags I will need and to plan how they will be used. On the left, I list the planned targets. On the top, I list the potential conditions. The matrix helps identify potential issues with the condition tags, and it later serves as both a reference for team members and a good training tool for new team members. The condition tagset editor and the Variable set editor both include a “Comments” column. It’s a simple way to explain how, when, and why a condition or variable should be used. The condition tag matrix must be updated when a new target is added and adjusted if needed when there is a major change to the project, such as a new module. It should also be regularly reviewed to ensure that it meets your long-term goals and requirements.

Team Authoring

Ideally, each member of a team has a clear understanding of their assigned tasks, the status of each file, and the style/writing guidelines they should be applying. I use file tags to track the author (or authors) for each topic and to assign a status level (e.g., draft, ready for review, final). All team members can then sort the topics by author in the File List (View > File List) and we can track our progress using the Used File Tags report (Analysis > Used Items > Used File Tags).

I prefer to create a style guide in my global project and import it into each “child” project. It’s much easier to review the style guide when it’s part of the project rather than a separate PDF file. It also allows team members to copy and paste examples into their topics.

Troubleshooting

Flare includes several troubleshooting reports that can be used to find and resolve issues within project documentation. I run the Summary report as part of my final build checklist. It provides a comprehensive list of any potential project issues, including broken links, undefined styles and conditions, and unused topics. Potentially serious issues are listed in red. You can double-click an issue in the Summary report to open a more detailed report and resolve the issues.

In addition to the Analysis reports, Flare includes over 100 informational reports. You can create an informational report by selecting File > New and setting the File Type to Report. Informational reports can include practically any information about the files in a project. I often create a context-sensitive help (CSH) report to identify CSH mapping issues and a micro content report to find any empty micro content phases/responses or duplicate phrases.

Several messages often appear when you build a target, and some of these messages could indicate issues that should be fixed. After you build a target, you can view all the build messages by selecting the build in the Builds pane and clicking Open Build Log. If you want to save the build log, click Save in the Log File toolbar.

Conducting a Project Checkup

Like a car tune-up, a project checkup is a scheduled review to identify and fix any lingering issues before they become serious problems. It’s also an opportunity to research new Flare features and evaluate whether you should apply them to your content. In general, I recommend a yearly project checkup. If a project has been extensively revised or reorganized, I recommend a project checkup about six months after the revision/reorganization.

During a project checkup, you should review:

  • The latest “What’s New” topic in the Flare help system
  • The Customer Showcase for inspiration and to see how other people are using Flare
  • The External Links and Absolute Links reports to review and test external links
  • The “Unused” reports to find files and style classes that you might be able to delete
  • The “Undefined” reports to find undefined condition tags, variables, snippets, and styles
  • Your Condition tag matrix to ensure it is still accurate and aligns with your future needs
  • Any project import files for broken links

If you do not regularly backup your project (in addition to source control), you should also export and archive your project during the project checkup.