Professionalism, Rants, and Support

Techcommdood related a flare-up over Flare on techwr-l, a mailing list strictly dedicated to work-related communication by and for technical writers. He went on to say,

All facts removed, this was an inappropriate post. Why? Well, it offered little information and, well, it was a classic rant. You have to ask yourself, "What value did this add to the community?"

One word: none.

I don’t know about that. It pointed out some potentially serious problems with Flare, a fairly new help authoring tool (HAT) that’s trying to dethrone RoboHelp. MadCap (the company that produces Flare) stepped up and offered to work with the ranter to fix the problems, so maybe there’s a happy ending to come. Whatever: being a Mac user, neither MadCap nor Adobe (RoboHelp’s current owner) gives much of a rip about what I want or need.

Dood’s point was to decry the unprofessionalism of ranting on a public forum, whether directly or through an intermediary (as in this case) — of course, there’s Techcomm, a forum for tech writers that’s meant to be 95% rants and silly jokes, but that doesn’t really count. But there’s several kinds of unprofessionalism on display here, and they can all be seen in the ranter’s rhetorical question (caps lock removed): “Why should I pay $700 for a product and then spend my time doing workarounds to get it to do what it should do automatically?”

First, the ranter didn’t mention whether MadCap had tried to fix the problems before the rant, or if they were even aware of the problem. If you’re going to spend $700 for a piece of software, you should ask for help and expect to get it… and if you’re charging $700 for that software, you should a) make something that doesn’t break; and b) make sure your customers don’t get to the point of ranting about you in public. (The latter is often something that small companies like MadCap actually do better than larger ones like Adobe.)

The larger unprofessionalism is depending on some pretty $700 piece of software chrome to do your work for you. Face it, fellow tech writers, HTML (or even XML) is not rocket science. We complain about those icky tags, then we wonder why we get replaced by “technical writers” with a certificate education, at half the salary. Then there’s the whole issue of trusting your work to a monolithic database, which destroys everything when it gets corrupted (e.g. the late, unlamented ForeHelp), or any other software that doesn’t allow you to easily extract your work out of it (Word).

I’m not saying that we should be building help systems by hand — but we should certainly be willing to get involved at a much lower level. HTML-based help, after all, is simply a wrapper around a series of HTML (and graphic) files that provides (usually JavaScript-based) niceties like search and context. You provide table of contents and index files — and the content, of course — and that’s it. You don’t have to work directly with HTML — but you should be able to use what your authoring tool gives you to produce HTML, then be able to clean it up and prepare it for use with the help system. Yes, it takes a little time, but so does importing stuff into a dedicated HAT and fiddling with your content there.

Probably the most trouble-free help-building system I’ve seen to date is Mif2Go with FrameMaker to produce OmniHelp, an open-source help viewer. I’ve also used groff to produce HTML that works well with OmniHelp — everything can be modified to work the way you want it to, with no $700 “license fee” involved. Why are we not taking more advantage of set-ups like this?

It’s time to take control of our operating environments and to start living up to the title, technical writer. We’ve let the word become little more than a way to distinguish what we do from journalists and fiction writers for too long now, to our detriment.