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?
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.
Sounds like a real problem. One thing to keep in mind is that unstructured conditional tagging is a decades-old technology. It is woefully obsolete and any heavy implementation of it will make that clear.
As FieryPantone hints at, structure-based condition tagging is a much more modern way to go. It is easier to apply, clearer to visualize, and much more logical to build automation upon. DITA is one option, but you may not need the full complexity of DITA. You will need structured documents though, which any serious tech writer should be using anyway.
If you want a sample of condition-based tagging, you can check out the following plugin and its tutorials:
Disclaimer... this is my plugin, but the software and all components are completely free, forever.
A new resource that just popped up from the folks at Scriptorium is their learningdita.com freebie site. Tom Johnson was blogging about it this week (http://idratherbewriting.com/2015/07/28/learning-dita-scriptorium-course/) where he summarized it as:
Learningdita.com is a free online educational resource created by Scriptorium for learning DITA. The initial course on their site, "Introduction to DITA," lasts about an hour and will introduce you to core DITA concepts and techniques.
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.
You 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...
...some background info on the implications of using multiple conditional tags.
Ah, that's what I was looking for! Thanks for the reference. The other posts have given me ideas on how to possibly approach the idea of converting to XML. I do have one project that I'm starting from scratch, and I could do it as XML to illustrate the increased ease. Our supervisor is aware of the situation, but doesn't know enough about technical writing to judge which is the proper course -- to keep what we have or convert. I am definitely living in interesting times...
(I like the visual of trying to herd a bunch cats in a field of catnip...)
35 years ago, when we didn't know about TEX and there was no FrameMaker at all I was defining (and my colleagues programmed) a text formatter on an IBM mainframe in Pascal. We had a construct scopes - endscope which could be nested. In the documentation we wrote that you should not provide more than 5 arguments to scope (e.g. Département names) and not do more than 3 nesting levels (e.g. output device types). Fortunately these limits were not stressed by any real text - but this was not the time of personalized cars ...
He did -- eight pages, with needed illustrations. He just didn't get the idea that other people may need to look at his set shorthand. I was military trained, with the idea to leave a clear paper-trail of all your work, because you may not be alive to explain it. (A civilian version is "hit by a bus.")
I would love to set this all up in XML! I've used that in other jobs, and my husband is an IT specialist (writes all my FrameScripts!) Convincing my colleague to "change" (that horrible word!) is like pulling teeth. Unfortunately, he is senior in this position, although I have much greater experience than he. This is the only position he has ever held.
I'm trying to eat this elephant one bite at a time.