The joy of being a Technical Communicator
I often find myself in a unique position where I see the funny side of language use or where I am consulted on best use of language. Two recent examples spring to mind.
The first was a quote by a celebrity who having had a hit record in the 1980s considered himself “vaguely famous”. Now I would say that you can’t be vaugely famous. You’re either famous or your not. It’s not relative or subjective. If someone has heard of your name, you are famous whether it is 10 or 10,000,000 people. “Vaguely famous” = an oxymoron!
The second example occurred last Friday when a colleague came and asked whether “Dr.” should have a full stop after it. “Yes”, I replied, “It is an abbreviation for “Doctor” and as such should always have a full stop.” The answer went down like a lead balloon but it was the follow up question that really made me chuckle. “Do you have any standards that says that we have to have a full stop?” The documentation in question was for a marketing leaflet which has its own style guide for which I am not responsible. Unfortunately, the style guide didn’t cover such idiosyncrasies so they came to the oracle for a second opinion. The documentation team style guide didn’t cover this either (we don’t have much call for abbreviated titles) but I suggested they stick with my suggestion.
It transpired the reason why my answer was unacceptable was that it generated more work that would take an additional 30 minutes to put right. It was only when I reminded them that they had already wasted that time and more involving the whole of the marketing team and now me and one of the Technical Authors, that they went away with their tail between the legs.
Tish! Tish! One must have standards!
The greatest baggage search story ever told!
In the dawn of time, before the great God of help authoring tools created RoboHelp, the world was a barren and unfulfillling place. Documentation professionals, especially those who maintained content for two or more audiences, worked feverishly at their keyboards with an unhappy listlessness. They held a forlorn hope that one day a tool would be created that would make the world a more pleasant and enriched place.
One day the prophet Macromedia (or was it e-help or Blue Sky) brought forth a version of RoboHelp with something called conditional build tags built in. These miracles of technology could be attached to topics or topic content and then used to exclude, or include, said content in the output. All you needed was an expression in the single source layout. Technical Writers saw that this was good and doth spoke with one voice, “This is truly manna from Heaven. Now we can maintain different content for all races from one set of source. It’s as easy as falling off yonder log.”
Indeed the world was a better place, but only for a short while. You see we Technical Writers got greedy. Not satisfied with the current functionality handed down to us, we wanted more. “MORE?” screamed the almighty Macromedia (or was it e-help or Blue Sky). “Does thou not knowest how difficult it will be?” A collective sigh could be heard from the heavens as we demanded the ability to add conditional build tags to Table of Contents pages. “Oh and whilst you are at it, what about other stuff as well?”
Just then, the clouds darkened and a crack of thunder rained down from the firmament. When the rain stopped, Adobe had bought Macromedia and a new RoboHelp version was forthcoming. Lo and behold it had implemented what we had asked for. We looked at it and sayeth, “Thank you, oh Omnipotent one. Now this tool can truly be called the King of HATs.”
And indeed it was. It even waxed lyrical whilst slaying those pretenders down the road at Madcap. Whilst rendering such sinners to an existence of functionality catch up, Adobe released yet another version (8) of the great tool RoboHelp. This one was THE one. It was a major redesign from the ground up and answered most of the questions unbelievers asked of it. It even allowed baggage file contents to be searchable, a feature previously only available to users of the RoboHelp Server.
But there was restlessness among the great unwashed, some of whom didn’t want their PDF content included in their user’s search results. “How could the great mighty one have allowed this to happen?”, they asked. But a savior was at hand in the shape of a little known file called SALIdxSvc12.xml. Lying unloved in RoboHelp’s install directory, this XML file suddenly found favor amongst those in trouble. It contains a list of file types that can be excluded from search results. So the miracle of the SALIdxSvc12.xml file was to remove the required <Type Ext=”.XXX”/> line(where XXX is the file extension of the file type to be excluded).
Lo and behold, we rejoiced and made merry. We just had to ensure that we restarted RoboHelp before creating our output and restoring the original file before working on any project that did require PDF content to be searchable. But beware as the small print has a warning attached. Do not try to add file types to the SALIdxSvc12.xml file that were not originally there. Such behavior will surely result in great floods and fires that will render your source code untouchable. You have been warned!
Update
Editing the SALIdxSvc12.xml file to exclude certain file types could also dramatically reduce your compile duration. It has been reported on the RoboHelp forums how a project of 330 topics and 2000 PDF files was taking seven hours to compile. After the SALIdxSvc12.xml file was edited, it took ten minutes!
