Guideline for using Conditional text

Question

I’m looking for guidelines on using conditional text. Our company has grown, and as the product line grew, the number of conditional text tags grew. We are up to 30 tags and still growing. I have been petitioning my colleague to start breaking this system down a bit, as I fear it is becoming a house of cards. Colleague has been here 20 years and grew with the system – it's the only one he's used. He sees nothing wrong with it. The tags are in his shorthand. When I mentioned that anyone new wouldn't understand them, his response was that they’d learn them eventually. Also, it’s starting to get to the point where certain sentences are being mis-tagged, causing numerous errors.

Are there any guidelines that I can reference that say when the usage of conditional text is getting too large so that it is not just my word?

Milmacrose

Arnis Gubins · Accepted Answer

The initial course on their site, "Introduction to DITA," lasts about an hour and will introduce you to core DITA concepts and techniques.I will urge my colleague to view it, and maybe if he agrees, we can work on this together. I greatly fear that it is a case of "this is the way we've always done it; I don't see a reason to change."I'm hoping to show him that there are new and better ways of doing things.--In the meantime, I was also hoping to find something concrete that would support me when I say that he has exceeded the "best practices" guidelines for use of the conditional text.MilmacroseYou might want to have a look at Matt Sullivan's & Sarah O'Keefe's book (Publishing Fundamentals - Unstructured FrameMaker 11 ;  Chapter 24) for some background info on the implications of using multiple conditional tags. Depending upon the model you choose (i.e. to either hide or show content based upon the condition tag), you can get into very complex situations with some items possibly requiring every combination of tags applied to prevent from showing (or showing) as needed. Even with simple single conditional tags, this can grow to a very large number of unique tags required (mathematically, you're summing a series of combinations). For example, [as used in the book], given a product in Light, Standard and Pro versions with Online & Print specific requirements for Mac, Windows and Unix, one needs 32 conditional tags properly applied. If you have some content that needs to appear in a couple of versions, than this easily climbs up to 47 unique tags. You'd be better of trying to herd a bunch cats in a field of catnip...

FieryPantone · Answer

Start by requesting Mr Conditional to help you (and his colleagues) by writing a short overview of the conditional tags he's already implemented, including (natch!) an explanation of when to apply each one.

Also, if it's your call, take a thoughtful look at the "extended product line" and its implications for documentation; it might be time to move to structured documentation and component re-use – in other words, tagging each block of information and selecting what you need, instead of using conditions to exclude what you don't need. If this is a new idea to you, try (for example) the short overview "DITA for the impatient" at XMLmind XML Editor: Documentation for XML authors.

Good luck!

Sign up

To post, reply, or follow discussions, please sign in with your Adobe ID.

Sign in to Adobe Community

To post, reply, or follow discussions, please sign in with your Adobe ID.

Scanning file for viruses.

This file cannot be downloaded