Being a Judge for STC and Removing Flare Conditions

I’m using this morning to finish up my FTCC judging, so I will just make a plug for STC and give a quick Flare tip.

First; the plug: You should submit something to your local STC competition next year. Besides making your company look good if you win something (one reason why they should pay your entry fee), you will also get detailed, custom feedback on your delivarables (the biggest reason why your company should pay for it, I guess).

Judges benefit, too. They get driven to the awards ceremony in a limousine exposed to the work of tech communicators in their area, and incentive to learn how to articulate what works and what doesn’t. Ask your chapter leaders if you can get something else, too, like a nifty judge’s badge for your web site or a recommendation on LinkedIn.

If you already entered an STC competition, please let me know how you process that feedback. Last year our team got pretty systematic about the feedback we got on our entries. We categorized the feedback, then went through it as a team to determine next actions. Most of the time the next action was to add it to the list for future discussion. But every week we discuss something and come up with styles and guidelines out of those discussions. So we have a plan for using the feedback. Do you?

The Flare tip: I guess my blog comes up if you search for “Flare removing conditions.” Since I once had to remove unnecessary conditions from some of my Flare projects, I’ll tell you how I did it.

The biggest thing to remember is to remove the applications of the condition before you delete the condition from the set. You can see where you have applied a condition at the topic level if you have the indicator boxes set to display in the Content Explorer. However, as we know, things do not always happen cleanly in the code when you do it in the GUI. Additionally, there is no quick way to find all applications of a condition within a topic. (Something I recommend you minimize, anyway).

No problem; you can search for the code that indicates a condition is applied using the Find feature. Search for <MadCap:conditionalText MadCap:conditions=”YOURCONDITIONNAME”> and remove the applications, one by one. I don’t think this is something you can fix all at once using Find-and-replace, unless you are finding the condition tags are empty. You can find and replace empty condition tags: <MadCap:conditionalText MadCap:conditions=”"><MadCap:conditionalText>.

The nice thing about this is that it will keep empty condition tags from causing those indicator boxes to do funny things. For example, have you ever seen an indicator box half-colored when you applied a condition? Half of the box can have the color of your condition and half can be blank, which can seem pretty odd. It can happen if you removed or renamed the condition from your condition set but didn’t remove it where it was applied.

As a reminder, if you import topics from a source project into a master project, you should do the find-and-replace in the source project first, then reimport, then do it in the master project.

Condition Guidelines for Flare Projects: Part 2

In Part 1 of this post, I listed our department’s new guidelines on applying conditions in MadCap Flare. Conditions are one way you can include or exclude content when you are single-sourcing in Flare. After The Project, our crash course in project linking and conditioning, our manager drew up some guidelines that we’re adopting for the next few months and trying out on a test project. I think they’re pretty close to finished, though. This is Part 2 of those guidelines.

Defining Targets

I define a target for every deliverable: User Manual, WebHelp, .chm help, System Admin Manual. If you have a separate target for each deliverable, you can set the conditions (and other settings) and leave them. Here’s what to expect:

• When a topic or paragraph has two conditions applied to it and the target is defined to include one of the conditions and exclude the other condition, the conditioned material will be included in the final output.
• When a topic or paragraph has two conditions applied to it and the target is defined to exclude one of the conditions and nothing is defined for the second condition, the conditioned material will be excluded in the final output.
• When a topic or paragraph has two conditions applied to it and the target is defined to include one of the conditions and nothing is defined for the second condition, the conditioned material will be included in the final output.
• When a set of topics or paragraphs has two conditions—one applied to some files and the other applied to some other files—and the target is defined to include one of the conditions and nothing is defined for the second condition, the material with the second condition will be excluded.

This last one was discovered while testing in preparation for these guidelines. I wish we had known this when we linked all the files up for The Project. This lets each writer only pull what they know they need from a slave project, with minimal interference with the other writers sharing the project.

Another tip: If you don’t choose define any condition settings in your target, and you’re building a help system, all files will be included, even if they aren’t on the TOC. Users will be able to find them in search.

Managing Condition Sets

In a nutshell, condition sets became as controlled as our CSS. Which makes sense to me.

• Do not rename the department condition set file or add any conditions to it.
• A new condition set file should only be added to support different versioning information
• Any new condition set file needs to be approved in advance by the Tech Comm Mgr or Team Lead.
• In most cases, Not For Users conditions should only be used to add information to the base files. That is, use conditions to add information on an upcoming release while maintaining the integrity of the baseline files.
• A new condition set file should follow the set naming convention. Within the condition set file, conditions should be added with the appropriate naming convention.

Version Conditions vs. Archiving

We determined that we don’t expect to use the version conditions much unless multiple development lines of a product are being maintained. We will archive a copy of our projects at each product release. We’ll use these archived copies to produce any deliverables we’ll need pertaining to that release. The working project will continue to be built upon those base files without conditioning for versions.

Tell Me Again Why I Like Conditions

Even though it took years off my life figuring out the conditions for The Project, I enjoyed it. I liked the challenge of knowing that when we found the right combination of conditions and linked projects, we would be sharing files where previously we had duplicated work. The moral is: conditions can do a lot, but they can’t do everything. And they’ll probably do something that you weren’t expecting, so leave plenty of time to QC.

Condition Guidelines for Flare Projects: Part 1

Applying Conditions

Conditions – how do I love them? Well, let me either count the ways, or count the duplicate, missing, unused, and capricious conditions that have made their way into our shared files. As soon as we began linking up our Flare projects and passing them around, it became apparent that someone was going to have to cut us off.

Some one had a condition for every reviewer: Joe, Mary, Tim. I had one for every status: To Edit, To Be Reviewed, Approved. I fought for that as a separate condition set, since it was convenient for seeing at a glance which files needed work. I was finally convinced to use a separate TOC for topics-in-progress. Like, duh.

And let’s not forget the conditions that were duplicated across multiple condition sets—some files had Print Only from applied from the Default set, others from the custom project set. I’m not looking forward to rooting those out.

After several combined hours of discussion, the some department guidelines were born. This first post covers our guidelines for applying conditions. In the second post, I’ll give our guidelines for defining target conditions and managing condition sets. These guidelines were written by our manager. The peanut gallery is all me. And if you’d like another good overview on Flare conditions, check out Paul Pehrson’s post about them. They seem to frazzle him less than they do me, though I don’t know if anyone can love conditions like I love conditions. That said; here are our guidelines:

Whenever possible, write around the need to use conditions.

• For example, if your text refers to a “chapter” or another type of text that is appropriate for a user manual, do not condition it out for a Help system. Rewrite the text to be applicable in both.
  This might seem to defeat the purpose of having conditions, but the more conditions you use the more likely that somewhere the conditions are at odds with each other. Each place that you apply a condition is a place that you have to check whether the outcome is what you expected.

When conditioning an entire topic or group of topics, apply the condition in the Content Explorer pane (not in the TOC). Do not apply conditions in the TOC.

• Talk of this rule started when we realized that applying conditions to the TOC did not remove them from a .chm or WebHelp build. That works to condition content out of a Word or PDF output, but in a help file, the topics will still turn up in a search.
• Additionally, some folks were applying the conditions to the files in the Content Explorer, as they should, but then also applying the same conditions to the TOC, for good measure. This was an unnecessary step, and also misleading for someone coming into your project.
• Actually, I would rather we took a stand on only having a single TOC, in which case we might have need for using conditions on the TOC. But since we are going with the rule for a few months, I will give linking TOCs another try.

Avoid applying conditions within a topic or to sections of a paragraph.

• If applying a condition to a complete paragraph within a topic (preferred use), apply the condition using the paragraph indicators on the left side of the screen. Applying and removing conditions in this way will ensure the underlying code is managed correctly. Two main reasons for this one. First, sometimes you have to go into the code to completely remove a condition. Better not to condition at the sentence level if you can avoid it. Second, if you are linking projects, importing a file only executes your topic-level conditions. For example, if you import a topics from a slave project based on whether they have the X condition applied, great. All the files with the X condition are applied. If you have the Y condition applied to all the Y product names within those topics, you can’t filter those out until you build a target. Each target can only use one combination of conditions. So if you are combining X and Y files into one target, they must have the same condition requirements.

The “NOT for USERS” condition is only to be used at the topic or folder level. Do not use it at the paragraph level.

• Inevitably, when trying to condition something as not for clients at the sentence level has come back to bite us.
  When a project has almost two thousand topics and a lot of conditions, some other condition is going to bring that content to the surface.

Okay, so once you have the perfect conditions applied with finesse and restraint, what next? Tomorrow I’ll post about defining how your targets use conditions, and about how to manage multiple condition sets in Part 2 of this post.

This Week in Flare Project Linking

You might know that Madcap introduced a project linking feature in Flare v.4. I’ve been itching to try it, and we got our chance when several of us were charged with providing a documentation set to a critical client that was receiving several of our products. The products had always shared functionality, but we previously documented those shared features in parallel. The time crunch of this project and the need to shine (it would be obvious and embarrassing if each of us presented our own takes on these features) pushed us to link up the Flare projects so that we could share that content and not make duplicate updates.

Some things I learned this week about linking up Flare projects:

You can move the linked files around without breaking things.

This might seem sort of basic, but it had me in a tizzy of concern before I finally just sat myself down and imported some topics. The topics come in at the same folder level they were at in the original project. For example, if the file path in the original project was “…Product/Menu/Option.htm,” when you import, the Project and Menu folders will be created in the receiving project, unless they already exist there. Then you can move the source files or the child files as much as you like. Flare will keep track.

You can pull in images, snippets, and condition sets by including linked files.

This feature just saves so much work. Flare uses linked images, and you can use a check box called “Include linked files” in the import file to import the images along with the topic. You can also bring in the condition sets and snippets that are used in the topics. If you want to make sure you don’t break links, and that you bring all the topics that are linked together, this is how to do it. I highly recommend bringing in your images this way instead of copying and pasting; otherwise you have to make sure you have the right folder levels in the Images folder of the receiving project, which is a silly pain. Plus, we created the original project from a Word import with embedded images, so many of the images were numbered rather than named. We would have had to hunt and peck for the images that were used in the shared files. Not fun for a large import.

By the way, you don’t have to accept all of the linked topics. Flare gives you a confirmation box to cherry pick files to include, plus you can filter by conditions. The conditions will override the linked topics feature, if you’re wondering.

If you create an import file but you don’t actually import anything, you could still overwrite files the next time you build a target.

We got burned with this yesterday. What happened was, I deleted a topic that I thought was redundant. Then I decided, well no, I would revise it instead. No problem, I thought, I’ll import that topic from a backup copy of the project. When you import, you can theoretically filter for such a topic by using a wildcard character (an asterisk) plus part of the file name, and I was curious to try that out. I had trouble getting the import file to find the topic, though, so I never did actually perform the import. I didn’t delete the import file because I thought I might use it later. I left it pointing at the backup copy, which was almost a week old. Gosh, that seems like a bad idea when I put it out there in black and white like that for all to see.

The next morning, when I attempted to build a rather small target from the project, Flare crashed repeatedly. I gave up and went to a meeting, and when I came back, my manager was in controlled panic, because for some reason the project had lost almost a week’s worth of work. “It’s kind of a big deal,” she said patiently to me on the phone from her desk, where the emails were flying between her and a network administrator. This was her way of saying that we were pretty screwed if we couldn’t figure out which wormhole the project had disappeared into. She’s such a nice person.

It took most of the day and a network restore to determine what had happened. It turns out that even though I never told Flare to import, since the import file existed, the files were updated anyway upon building. The lesson is this: either delete unused import files or don’t set the import file to automatically search for updates when you build targets. Oh yeah, and back up religiously, of course.

You can use a linked project to filter out unused files in a WebHelp.

We’ve got a WebHelp target that is significantly smaller than the primary target, yet all of the files that are in the project get included when we build the smaller WebHelp. This bloats the file size to the point that we can’t email the file. Since the WebHelp will be widely used by internal folk during implementation, that’s a problem. We tried a couple of the project hygiene tips that were listed on the Flare forum (clean the output folder, don’t build online targets to the same location), but they didn’t solve this issue. I think what we may end up doing is creating a new project for this deliverable and then importing the necessary files into that new project. We already have conditions set up for our various targets to supplement our TOCs, so theoretically we could use those to only pull the files for this internal deliverable.

Hurray, Project Linking

Overall, I am excited about the possibilities for reuse that this feature offers. Ours is a high volume shop, and we need all the help we can get in that area.

I’d love to know what you are doing with project linking in Flare. Do you have tips for me?

10 Steps for Importing Large Legacy Word Docs into Flare

I like the way Flare help uses organizational pages in its help system to organize content into a process. You can learn “About Indexing,” and within that topic, you can click drop down links to display a description of the Index Entry pane. You can click another drop down link to see the steps for adding an index entry, and so on. I think things are set up pretty well in the system, now I’m just ready for some important information to be added within that structure.

In particular, print documentation brought with it several points of pain. Importing it, outputting it, formatting CSS for it. Over the course of our Flare implementation, as my knowledge of help authoring concepts and technical skills have progressed, I have found that Flare help does have information that I would have sworn a few months ago was not in there. Of course, that’s because I have provided the context for myself. Now that I know how the bits of information needed for print imports and targets work together, I can find most of them in the help system.

Here is an overview of importing legacy Word documents that I hope will find folks that were where I was six months ago:

1. Creating the project.
   Our team has a set of common files that has grown over time to include master pages, a set of topics about the help system, condition sets. The first shared file, which we produced as soon as we could, was the department CSS. Another important set of shared topics is the standard preface for our user manual. Since this is where we use the two master pages that supplement our main master page, it’s important that everyone had that content split into topics in the same way We keep these common files in a master project on our server. I’m curious how other teams handle common files.
2. Creating the folders in the Content Explorer.
   These are the folders where you access the topics to edit them, and their organization should be somewhat standard across projects, in my opinion. I also recommend that they mirrored the structure/TOC of the legacy content. I added these folders prior to importing legacy documents so that I could sort the imported content into the appropriate folders quickly. If you’re just sorting the topics that are created during import into the same chunks, or chapters, that you were accustomed to them being in, you can reduce the time it takes to produce your first set of outputs.
3. Dividing the legacy manual into separate Word documents.
   That way the topics created by each import could be easily sorted into the CE folders. For example, a Word doc for every chapter, then break each chapter down into a Word doc for every section of the chapter. In our case, a section consisted of a set of procedures and a set of reference items. Since headings for each information type were distinct and standardized (gerunds for procedures, ‘such-and-such description’ for reference), once I had a Word document for each section I could easily sort the resulting topics into the CE folders.

 

4. Preparing each document for import.
   Depending on how well your imported docs play with Flare, you may want to remove cross-references, page breaks, section breaks, or logo pages before you import. You can test-import a document or two to see what doesn’t come over well.
5. Creating a CSS with styles that corresponded to the styles in the Word template.
   Your imported content is formatted by a template, right? This decision saved us from having to design a CSS from scratch. It also saved us from having to debate a revamp of our styles—if it was in our Word template it went in our CSS. For the first version of the CSS, that was the end of the discussion. You can create a CSS based on your Word styles by specifying that Flare create those CSS styles during import and then refining the results. I don’t think this is what our CSS guy did, though.
6. Mapping Word styles to the corresponding CSS styles during import.
   I did this for each style that I could. You can’t map to list styles, though (at least not in 3.1). This was really too bad, considering how much of our content was procedures. If any one has a guess as to why this wasn’t done, I’d be interested in such a speculation.
7. Formatting imported content.
   Imported lists all had to be combined, because imported list displayed each list item as a separate list. Imported tables didn’t use table styles if there was a paragraph break in the cell. No biggie, except some cells didn’t have paragraph breaks, and so used table styles. Many links and cross references were broken and so were only serving as placeholders for corrections. Many of our images were stripped out or placed in the wrong location.
8. Creating TOCs that mirrored the structure of the imported content.
   This is the same idea as I mentioned in regards to the Content Explorer. I made my TOC match the manual that I imported. This resulted in quick turnaround for the first iteration, and that means I had more time in the second iteration to design how I wanted the help content to vary from that structure.
9. Formatting each style for online and print.
   Flare lets us specify a medium for each of our CSS styles—make h1 look Fuschia and 18 point online while it remains a prim and proper black for print targets. Another reason why you don’t have to rearrange content or styles much for your first iteration—leave the same style applied; just change its appearance according to the medium.
10. Retaining heading numbers.
    This concept of working your CSS mediums was most helpful for headings. For us, headings 1-5 generated new topics during import. As a result, the most common first heading for a topic was heading 5. This did not look beautiful for online topics. At the same time, we didn’t want to have to try and reapply the correct styles when our topics got back together again in a Word target. So, we formatted headings 1-5 all the same for online medium. They all looked like heading 1. Then we formatted them uniquely for print.

Please do let me know if you have a tip for importing to share!