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.

Guidelines for Linking Flare Projects

I’ve talked a bit here about my experiences linking projects Flare. Recently, we brought new writers on to the project where we use linking, and it became apparent that we needed some sort of written guideline.

In previous releases, we experimented and tested quite a bit to arrive at these guidelines, and the linked projects grew weedy with extra files, TOCs, and rogue condition sets. It can happen quicker than you might think. This did not facilitate a new writer jumping right on the project and feeling confident about not breaking something. Our department tries to focus on creating repeatable processes, as I imagine yours does, too. Be aware that the process of linking projects has proved to be a challenge to that general principle.

Why Link Projects?

The benefit of linking Flare projects is that you can maintain help topics that are used in more than one project in their own separate project. This lets you share those topics with multiple help projects at once. An example of when you might want to do that would be to document software program A, which is not a standalone product, but a source of common code used by programs B, C, and D.
There is another reason to break topics out into their own project—it lets multiple writers work on a project at once more easily than if they were working together in one project. Recently, on a project with an aggressive schedule, we have started to work collaboratively, which was new for us. We have traditionally done one writer to one release.

For this project, we identified some code that was shared between several projects. We then moved the help topics that document those windows to their own Flare project and imported them as needed into master projects. This lets multiple writers work on the same release, but in separate projects. Without source control, this was a way to avoid getting in each other’s way.

Definitions

• Source project, or slave project – a project from which you are pulling help topics into your project. Its purpose is store help topics that are used in other projects. You do not build help systems from a source project, you only edit help topics. In the above example, the program A Flare project is the source project. It is the “source” for the help topics related to program A.
• Master project – a project into which you pull help topics from source projects. Help systems are built in master projects, but you don’t edit help topics you have imported from source projects. In the above example, the projects with help topics for programs B, C, and D would be the master projects.

Source Project Guidelines

Remember, we developed these guidelines partly because we don’t have source control. I don’t know much about source control products, but I’m guessing it would be better practice to have source control rather than to rely on this honor system. We do still run into issues.

• All files are named with a naming convention that starts with the initials of the project. For example, all html files in the program A source project start with “aa_.” This lets you identify them at a glance once they are in the master project. The link icon will also identify them, but what if you break the link?
• The TOC in a source project is for reference only, and may or may not be maintained. It is not used to build a deliverable.
• When you add a file to the source project, you must import it to the master project and add it to the TOC in the master project.
• Any necessary conditions on the file must be marked here, in the source project. Conditions on folders are applied in the master project.
• Do not rename file names in a source project. Otherwise, they will not properly overwrite themselves in the master project.
• Do not rename folders in the source project, for the same reason. Folder levels in the source project must match folder levels in the master project.
• Do not move files to other folders in the source project, for the same reason.
• When you add a file to the source project, you must import it to the master project and add it to the TOC in the master project.

Master Project Guidelines

• Conditions at the file level must be applied in to the topics in the source project.
• Conditions at the folder level must be applied to the folders in the master project.
• Any find-and-replace searches should first be done in the source projects, and the files should be reimported before doing the find-and-replace in the master project. This is important, as Flare will not respect linked file restrictions during a find-and-replace search.
• When you add a file to the source project, you must import it to the master project and add it to the TOC in the master project.
• Do not move imported files to new folders. Otherwise, they will not properly update when you import from the source projects, and there will be duplicate topics. Folder levels in the source project must match folder levels in the master project.
• On the target files, disable auto-sync of linked files. This prevents the project from re-importing files from the source projects when you build.
• To import update topics into the master project from the source projects, open the import file and reimport.

Working with Multiple Writers

• While a writer is doing a find-and-replace search, it’s best not to work in the same project as that writer, or at least not in the same section of the project.
• While a writer is building a document in the master project, no other writer should be working in the master project. If auto-syncing files is disabled for the target they are building, then other writers may work in the source projects.
• While a writer is importing topics into the master project from a source project, no one else should work in either project.
• Be careful not to work in the TOC file at the same time as another writer.
• Multiple writers can work in the same project at the same time, but not on the same file at the same time.

Does your team collaborate on Flare projects? How do you stay out of each other’s way when you share files? For us, communicating about this is the biggest help, but it’s also one of the biggest challenges.

Automatic Table Headers in Flare – Guest Post

Maybe you’ve seen me post here, or on Twitter, about our department CSS guy, Matt. Well, he actually does a heck of a lot more than our CSS–he maintains all of our standard department files such as page layouts, table styles, and skins, designs the nitty-gritty, mysterious, techy bits for us when we come up with a department standard, engineers the solutions when management asks for the near-impossible, and provides daily panic support. You need someone like him on your side if you want to be successful with Flare, in my humble opinion. At least, if you’re a shop that will use more than the proverbial 20% of the software.

So, Matt’s been promising a guest post, and here it is–yay! Background: One of our latest team discussions involved whether all of our various tables should have header rows. We’ve hitherto been inconsistent across projects. The upshot: we should all use header rows, and they should be consistently worded. Matt, can we do that? Turns out, not a problem. Read on…

Automatic Table Headings (2 Column Tables)

If you are like me, you might have hundreds, if not thousands of table headings in your documentation and maintaining these headings can be a nightmare. Keeping your tables consistent in documentation can be automatically maintained in your documents with a few very easy steps.

Before you begin, analyze your project(s) and recognize your needs. For my team we needed tables that had Fields / Descriptions and Buttons / Descriptions in the headers.

1. Create a new table style sheet (or edit the existing table style sheet, if you are feeling lucky …. punk) by selecting Project > Add Table Style.
   The Add New Table Style Sheet window is displayed.
2. Enter a file name and click the Add button.
   The table style sheet is created and added to the Content\Resources\TableStyles folder
3. Right-click the style sheet and select the Open with > Internal Text Editor option (or use an external text editor like Notepad++).
4. Locate .TableStyle_TABLENAME_Head_0_0_RowSep_ColSep in the table style sheet code.
   
5. Add mc-auto-number-format: Fields; to the code, similar to the image above. This attribute will be applied to every column except for the last column in the table, if you add additional columns to the table, the auto text: Fields will be displayed.
6. Locate .TableStyle_TABLENAME_Head_0_0_RowSep_ColEnd in the style sheet code.
   
7. Add mc-auto-number-format: Descriptions; to the code, similar to the image above. This attribute will only be applied to the last column in the table.
8. Save the table style sheet.
9. Insert a table by selecting, Table > Insert > Table. Select the new table style sheet and be sure to include one header row. The final product will look like the following:
   

Note: I used the following to create this procedure:

• MadCap Flare v.4.2.1
• TechSmith Jing
• Notepad++

But what about…

Great, we’ll have auto-text in our table header rows. But what about those thousands of inconsistent tables we’ve already got in our projects? If I recall, in the meeting I said, “We’ll just do a find and replace.” Right, Matt? Heh. Stay tuned.

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.