Are there "best practices" for using Conditional Text?

[milmacrose]

(Using Unstructured FM 11 in Windows 7.)

I have 30 years of legacy FM files with conditional text reflecting 30 years of company growth. When there were a few differences between models, this was fine. But as things grew, more and more conditions grew. Each file is looking more like a file folder, instead of a stand-alone file; some files have no unconditional text in them other than the title. When I turn on "show all" and "show conditions indicator," I get a rainbow. There are approximately 40 various conditions in our main system now, such that updating them is a nightmare.

I'm trying to get a good idea on some "best practices," so that any newly created manuals don't fall into this pattern. -- And perhaps I can figure a way to dismantle the still-live legacy documents.

And, no, we are no where close to being able to move to structures XML. I looked into that already and can't justify the cost. It's just me and one 25-year (seniority, not age) colleague who doesn't want anything to change, since he grew up with this system.

Indyrose

[Arnis_Gubins]

What approach to Conditional text is being used, i.e. old FM style to "hide" content or new conditional expressions to "show" content?

Are you using text insets for some of the conditional content? This creates a more modular approach and may be easier to maintain with multiple conditions.

[milmacrose]

The old "hide" version. No text inserts. This illustration below is a typical book setup for an operator's manual -- we have around 15 base models with multiple variations of each base model. In some instances the differences between each file can be as simple as changing "gasoline" to "diesel" -- but in other files (specifications comes to mind), there is a distinctly different information for nearly each model and variation.

Keeping with the concept of sole-sourcing, many of the same parts/procedures are used in different models, which makes the text common across many models. It made sense when there were just a few models, but now... -- and our product line is growing. Each time we've added a product, we've added two conditional text tags (one for current-only and one for parts history).

[Barb Binder]

What a great question. It would be nice to see multiple contributors to a list of best practices.

I'll kick it off:

1. Mishandled spacing is a nightmare. In the case of changing gasoline to diesel, or updating phrases with in a paragraph, or sentences in a paragraph, make it a habit to always tag the leading space. For example, gasoline diesel
2. Or, consider only tagging whole paragraphs.
3. Condition Indicators: use either a line style or a background color (or both) as a condition indicator in addition to the color so that you can proof the leading spaces.
4. Use keyboard shortcuts: Control 4 to assign a tag, Control 5 to remove a tag, Control 6 to remove all condition tags from the selected text.
5. Consider assigning tags in the same order. For example, Get someone else to put gasoline diesel in your car truck so that your hands don't smell for the rest of the day.

[jaggedpeak]

I was waiting for someone to start 🙂

Hadn't thought about keyboard shortcuts, but the other four items I agree with wholeheartedly (do them myself 🙂

Couple of additional very general points:

• Add an "writer's instruction" document to the book (at the top or bottom, and Exclude it from printing. This document would explain what each condition is for, when to use certain combinations of conditions, what the conditional expressions (if you're using any, to combine multiple conditions) actually do, etc.
• Always keep in mind maintainability. milmacrose indicated there are 15 models with variations within. It may be time to split into two or more books, each containing very similar models. When a doc reaches a point that maintaining the conditional text is more effort than maintaining separate books, it's time to do a re-think. Not just for *you*, but for whomever has to maintain and expand upon the documentation suite in the future.
• Tables - Determine if content should be conditionalized with cells in a row, or if 'duplicate' rows should be created for each condition. I had done the former originally, but it became very ungainly to manage. I found conditionalizing duplicate rows to be far more maintainable.

[milmacrose]

Some things I have also found are:

• Be sure to use a clear naming convention so other users know specifically which version goes where. Avoid in-house jargon for naming tags, as that may change or grow. (Example: For our first hydraulic unit, and the office just called it "the Hydraulic." The tag was simply made "hyd." Now, most of our units are hydraulic, and new people don't know what all that tag reflects.)
• If the content is totally unrelated to each condition (no shared unconditional text), then create a separate file.
• Limit the number of conditions to determine a breaking point for creating an new document.
• Be mindful of your paragraph end tag. Sometimes highlighting misses that, with some nasty results.

BarbBinder, your #1 is killing me right now! I want to smack some previous authors.

[Barb Binder]

BarbBinder, your #1 is killing me right now! I want to smack some previous authors.

I guess I shouldn't laugh, right?

Seriously, when I bring up Conditional Text in class and a student blurts out "I hate it" or "It doesn't work!" I always follow up, and 9 times out of 10 in comes down to spacing issues. It's a big one.