When You Rule the Tools

About a week ago, I complained about our tendency as tech writers to become slaves to our tools. Tonight I provide a counter-example — what becomes possible when you, the technical writer, is in charge of the tools.

At work, we’re building a box with built-in Wi-Fi capabilities and routing. Since that’s a fairly well-explored theme, we contracted a company in Taiwan to supply the Wi-Fi router. Like most routers for home networks, this one provides a web-based interface to configure the box, with links to context-sensitive help and a global glossary. As it turned out, the help that they furnished us was already owned (copyrighted) by another company. Since I work under the same department as the people driving this particular product, they brought me a working prototype and asked me to rewrite the help.

I’d seen an earlier prototype a few months back, so I already knew what was there. This time, though, I hit “View Source” in the browser — and was presented with a mishmash of HTML and <script> tags. Digging a little deeper, I realized that every single string in the web interface was being written by ECMAScript (the polite name for JavaScript hockkkk, ptui aka JavaSchit). The strings were stored as variables in files called language.js and langcont.js. The names explained the method to their madness: translating the interface requires changing only two files instead of 30.

Looking at the text itself, I was less than thrilled — we make stuff for cable companies; the help text talked about DSL and even ISDN, but not cable — and I had some better descriptions for other terms. The bolded term was run into the rest of the paragraph instead of broken out into a glossary-style list. I needed to add some cable-centric terms and remove the DSL- and ISDN-centric stuff.

So I fired up a text editor and got to work. It took all of five minutes for me to realize that I was going about it the wrong way. The string variables look like this:

h3='<b>Term</b> The definition…';

So if I wanted to add a new definition in between two existing ones, I’d have to either renumber everything following or create variables like h3_5 in between. Meanwhile, there was a corresponding <script> call in help.html:

<script language="javascript" type="text/javascript">dw(h3);</script>

To turn down the bloat a little, they had created dw as an alias for document.write. But the thing was, for every term I inserted or deleted in language.js, I’d have to make a corresponding fix in html.help. Since this is tedious, repetitive, kind of stuff — and I’m lazy — I decided to let the computer do the work for me. With a few global search and replace runs, I turned my text into HTML and then banged out a couple of scripts to transform it into the format needed by each file. It took an hour or so to get the scripts working, but I’d still be pounding on it if I had to do it by hand.

This is the kind of thing that you can’t do, or at least do easily, in Microsoft Weird or even FrameMaker. Even if it were possible, it wouldn’t be nearly as efficient. Sometimes, you even have to make tools to do a custom job on the spot. But when you rule the tools, the tools do the work for you so you can engage in some good old guilt-free slacking.