Darren Barefoot
Darren Barefoot


Technical Writing

Discusses the profession of technical communication

August 27, 2003

There's been some engaging interview stories on the technical writing list TECHWR-L recently. The best one is from list comedian Andrew Plato, who discusses the peculiar dress of one of his interviewees.

As I've been going to more potential client meetings and interviews lately for Capulet, there are a number of anecdotes that I've wanted to convey. Sadly, I'm unable to, as many of my clients and potential clients read this site. So, I'm collecting them for some kind of essay on weird interviews in the future.

10:43:46 AM  Permanent link to this entry    Trackback []    Technical Writing

August 26, 2003

I've added five new exhibits to the Hall of Technical Documentation Weirdness. Don't forget to check your instruction manuals for weirdness and send them along to me. Particularly the cheaper electronics. In my experience, the cheaper the product, the weirder the manual.

9:39:31 PM  Permanent link to this entry    Trackback []    Technical Writing Technology

July 29, 2003

Thanks to my brother Kevin, we have our seventh exhibit in the Technical Documentation Hall of Weirdness. Feel free to send me your weird and surreal tech docs.

1:34:19 PM  Permanent link to this entry    Trackback []    Mixed Bag Technical Writing Technology

July 8, 2003

Among other things, I'm a technical writer. It's been my bread and butter for the past six years or so. As one does, I've collected some examples of good and bad technical writing over the years. Most is unremarkable.

Yet, a few pieces defy description. They're utterly bizarre, madcap, surreal or otherwise strange. To honour this zany detritus, I've started the Hall of Technical Documentation Weirdness.

It's in its infancy at the moment, so if you've got any weird examples, feel free to send them along. I'm not looking for bad tech writing--there's plenty of that out there. I'm looking for the curious and the inexplicable.

9:02:11 AM  Permanent link to this entry    Trackback []    Technical Writing Technology

June 17, 2003

As ComputerWorld reports, the people at Doloitte Touche Tohmatsu (which always reminds me a little too much of Wolfram and Heart) have just released Bullfighter, 'a consulting jargon fighter' that plugs into MS Word and PowerPoint. It's free for thirty days, and you basically you open a document and click the "Bull Index" button on a new toolbar and it tells you how much bollocks you've written.

Mostly, it evaluates the document for common marketing and sales terms like 'synergy' or 'extensible'. It also applies something called the Flesch Readability model to evaluate how easy-to-read your document is (checking things like sentence length and syllable count).

I applied Bullfighter to a white paper I recently got, and scored a decent 79 on the Bull Index, but only a 5.2/10 on the Bull Composite Index (a complex combination of the diction evaluator and the Flesch analysis). Then I ran it on an article I wrote and, while I got 95 on the Bull Index, I once again got 5.2/10 on the BCI. Am I that predictable?

While this isn't going to replace a good editor, it might help reduce the ludicrous marketing-speak one regularly sees in press releases and on Web sites. Its most useful function is to highlight those words. For example, the aforementioned white paper has four occurrences of 'paradigm' and two of 'scalable' and 'seamless'.

Just for fun, I tried it on three of Deloitte's press releases. They all scored well on the Bull Index, but turned up a 3.3, a 4.5 and a 4 on the BCI. Work on that, people.

2:24:52 PM  Permanent link to this entry    Trackback []    Technical Writing

June 4, 2003

That's a reference to Being John Malkovich, in case you missed it. So here's a nutty little thing. Recently I've been musing on writing something fictional about a guy who's obsessed about remembering everything. So, he goes to extreme lengths to develop some software/hardware where-in he documents everything he can about his own life. Of course, knowing that all that data is stored somewhere else just addles his own memory. Anyway, not that original, but something to kick around while waiting for the elevator.

It turns out that I have God-like powers. For I've apparently created this man out of nothingness. Will Ludwigsen's alive and well and living in Florida. From his Web site:

In May 2001, I wrote a Visual Basic 6 application that reads, writes, and searches records in a database. Each record includes a date and a memo field describing the events of that date. I also added functionality to build documents including all of the records in a biographical timeline, as well as display the events that happened on a given date of the year. I can tell you, for instance, what happened today in my personal history.

The database currently contains about 1400 records, meaning that I know exactly what happened on that many days of my life. A small fraction, but better than nothing.

I use the database as a diary now, entering each day's events in sometimes excessive detail. The problem is that, unlike the historical records, the current ones cannot be prioitized. Who knows what will be important about today?

I found him while looking for weblogs by technical writers. If he were really brave, he'd expose his database on the Web. That'd be fascinating. Will, Web service-enable that puppy, would you?

And people say us technical writers are a bit detail-oriented.

9:56:32 PM  Permanent link to this entry    Trackback []    Technical Writing Technology

June 3, 2003

My Irish colleagues and I invented a good phrase. It refers to an employing who is seething, apathetic or otherwise showing signs of a quick, violent exit:

"Oh, that's Bob. He's just in his cubicle planning his postal route."

This, of course, refers to that popular phrase "going postal". And to this infamous (and stupid) video game (caution, booth babes--and Gary Coleman!--ahead).

3:55:56 PM  Permanent link to this entry    Trackback []    Technical Writing Words