Duct Tape Technical Writers

by Tom Johnson on Sep 28, 2009
categories: technical-writing

Keith Soltys recently highlighted Joel Spolsky's thought-provoking post, The Duct Tape Programmer. Joel praises the practical programmer who puts aside snobbish practices and simply goes for the quickest way to finish and ship a product. In his post, Joel sounds a bit like Holden Caulfield from the Catcher in the Rye. He writes,

Here is why I like duct tape programmers. Sometimes, you're on a team, and you're busy banging out the code, and somebody comes up to your desk, coffee mug in hand, and starts rattling on about how if you use multi-threaded COM apartments, your app will be 34% sparklier, and it's not even that hard, because he's written a bunch of templates, and all you have to do is multiply-inherit from 17 of his templates, each taking an average of 4 arguments, and you barely even have to write the body of the function. It's just a gigantic list of multiple-inheritance from different classes and hey, presto, multi-apartment threaded COM. And your eyes are swimming, and you have no friggin' idea what this frigtard is talking about, but he just won't go away, and even if he does go away, he's just going back into his office to write more of his clever classes constructed entirely from multiple inheritance from templates, without a single implementation body at all, and it's going to crash like crazy and you're going to get paged at night to come in and try to figure it out because he'll be at some goddamn “Design Patterns” meetup.

Joel's main idea is that "you're not here to write code; you're here to ship products" and that "a 50%-good solution that people actually have solves more problems and survives longer than a 99% solution that nobody has..." In other words, better to have a product that half functions than no product at all.

At the end of Keith's writeup of Joel's post, Keith asks,

I'm sure you could make a similar distinction among technical writers, although I'm a little too tired right now to come up with good examples. Toss in a comment if you think you can.

Are there such beings as "Duct Tape Technical Writers"? Why, yes. You've seen the guy who spends hours agonizing over whether to use a comma or semicolon, flipping back and forth as if the world depended on it, when he knows perfectly well that users won't care at all. I think we too often have a tendency to polish our prose as if we're submitting the content to The New Yorker.

In reality, the user just wants a brief, clear explanation of a concept or task. The user will glance and skim -- reading behaviors hardly worthy of the elitist grammarian who argues the finer points of "which" versus "that" in restrictive clauses.

I might leave the argument at that, if it weren't for Sarah O'Keefe's recent post, A Strident Defense of Mediocre Formatting. Reacting against criticisms of DITA's plain formatting, Sarah asks,

How much value (in the form of improved comprehension) is added to a technical document when you are able, in the words of commenter Brian Harris, to “lovingly handcraft” each page?

How much value (in the form of cost avoidance) is added to an organization when you are able to spit out a reasonably formatted document in a few minutes?

Sarah concludes that handcrafting your format increases costs dramatically. As a result, "fewer people get to see it." Essentially it's Joel's same argument: Better to get it out there in the hands of more people more quickly instead of tediously slaving over the content, eternally polishing the format and never getting it out there at all (or costing your company thousands of dollars to do so). It's good enough, dang it. Ship it. Users won't really see the difference or care.

This discussion hits a pain point for me with my practice of quick reference guides, which rely on custom formatting and design that can often take a while. Perhaps I'm compromising my work efficiency at the expense of extra design that, in the end, no user really cares about?

To be fair, I don't have to worry about translating these guides, but perhaps I should adopt a standard format, something that I carve out of Flare's page layouts, such as a dual column design that isn't concerned about fitting text into little spaces in aesthetic ways.

The same might be said of blog posts. Is it better to crank them out and get the information out there in a timely way rather than labor endlessly over style and flow? Is there an argument for being a Duct Tape Blogger too?