Duct Tape Technical Writers

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?

Madcap FlareAdobe Robohelp

This entry was posted in general on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS, email, or another method. To learn more about me, see my About page. You can also contact me if you have questions.

21 thoughts on “Duct Tape Technical Writers

  1. Karen

    I read the Joel Spolsky post via some other already forgotten path, and I paled at his “drop the unit tests” part. Development here has been on the Agile path for nearly 2 years now, and we still have a way to go. We “get it” (somewhat), but we still have to explain our behavior to the consultants who rush up with a “tweak this for me yesterday” task. I keep explaining how much time we’ll all save if they’ll prepare a unit test at the moment some amazing piece of code is born in their minds; how it’ll save lots and lots of explaining even a mere 5 minutes into the future, not to mention save my sanity when I need to add this gem to the documentation.

    I won’t hide the Spolsky post from colleagues, however. I’ll still defend unit tests. I think these articles push us to think. Instead of having us endlessly bob our heads in agreement and shaking the last remnants of unique thought onto the floor, these articles have us commenting and blogging and discussing. Best of all, they should have us thinking inside our heads: “how does _that_ bit of info apply to _my_ situation?” My developers may interpret him literally and say, yay! no more unit tests. Then I’ll tell them why we must continue to make unit tests – to train to make them a natural part of our workflow and not some onerous, tedious burden.

    I take away the idea of building good practices into workflows so the basics, the checks and balances, etc. are pretty much intact all the time, every time, but that there must be room for some drive-by documenting now and then (when we can quickly weigh the factors and justify such behavior.)

  2. Jim

    Spolsky certainly identifies the mantra of the first decade of the 21st century: just ship it. Why I agree, the place for template writing, bit players is no longer applicable, we should dread succumbing to mediocrity.

    However, what he and Soltys fail to understand is the end result, not just the milestone of code development met. All the loose ends that result from hastily written code (and any hastily produced product) end up costing a lot more money in customer service support then is ever exhausted in product development. In most cases front line CS needs to defer to second line support, which always ends up being the code writer (or product enginee) who has dear little time to do so. So what is a better way to approach the issue. Spend time up front and build better code, or solve a problem when you are hastily coding another project for an obscenely short deadline?

    Somewhere along the line, product developers gave up fighting for time for quality. And now we are instead learning to “adapt” to the new environment we are handed: the land of mediocity. There was a time when it was a joke for anyone to use duct tape as a repair solution. To use it for a production solution was unheard of. Why acquiesce to it now?

  3. Paul K. Sholar

    Doing nothing is definitely better than doing something so incorrectly that it has 100% chance of needing a fix. Bottom line: Understand first what it is you’re supposed to be doing.

    1. Richard L. Hamilton

      Paul, I agree 100% with your second sentence, but drawing from the programming world, any non-trivial program has a 100% chance of needing a fix at some point. The same is true for any non-trivial documentation.

      Understanding what you’re supposed to be doing includes understanding what the criteria are for shipping the product. The balancing act is finding the point where shipping now, flaws and all, is better for your audience (and your company’s bottom line) than shipping later with fewer flaws.

      1. Paul K. Sholar

        Incorrectness is different from, and worse than, incompleteness. Incorrectness must be addressed after product release to maintain credibility with customers, whereas incompleteness can be mitigated in advance by a statement to customers about the product’s intended functional scope.

        Paul K. Sholar
        http://twitter.com/bkwdgreencomet

  4. Richard L. Hamilton

    I also read the Spolsky article, and the point I found fascinating was not the question of unit test; I’m pretty sure from reading Spolsky’s other writing that he knows how to create quality software.

    The points that struck me are 1) that complex programming environments can lead to lousy software, and 2) that pushing for 100%, when 50% will do the job, is dangerous.

    The parallel for us as technical writers is our chronic fascination with the latest technology, be it single sourcing, DITA, content management systems, or whatever is next in line, along with our ingrained need to create perfect prose (I call it the copy-edit virus, and admit that I have a particularly virulent strain).

    We can’t ignore the technology and we don’t want to write garbage, but we also need to keep things in perspective and not let anything get in the way of creating documentation that is timely and useful.

  5. Mike Starr

    I think those of us who’ve been around for a while will remember a participant on techwr-l by the name of Andrew Plato. Andrew was hounded out of participation on techwr-l by the group he identified as “font fondlers”. Andrew’s response to font fondling? Just shut up and write.

    I tend to be of the duct-tape technical writing variety with a modest difference. I’ve got a built-in template in my head that I can create on the fly whilst working on any documentation project. It doesn’t take up any of my time to create the template and I don’t have to fiddle with formatting. I don’t concern myself with formatting and/or font fondling as a part of my everyday life. This approach makes me a whole lot more productive.

  6. Sarah Maddox

    Great conversation, Tom! I think the duct tape tech writer is one of those ideas where the truth is in the overall impression. When we start examining the proposition in detail, some flaws become obvious. And hence the opportunity for a very interesting conversation. :)

    Readers do need those simple and clear instructions and explanations more than anything else. So if that’s all we have time to publish by the deadline, then we shouldn’t let the deficiencies in form, nor even a lack of detail, stop us from publishing. 

    I also think that form and style are very important, especially when it comes to engaging our readers and community authors in the documentation. 

    If we have the luxury of some quiet time immediately after each release, we could have a long-running project to improve the format and styles incrementally with each release. This works especially well in an agile environment and where the documentation in available online as well as packaged.  

    Cheers, Sarah

  7. Andrea Wenger

    Tom, with quick reference guides, I *do* think there’s value in spending a good amount of time formatting. Your goal is to get the most information to the customer in the least amount of space, while ensuring that the document is readable. Chances are, the savings that result from fewer tech support calls far exceeds the cost of the time you put in.

    To the question of whether tech writers should agonize over comma use–no, they should learn the rules of comma use, and follow them. If you’re not sure what the rule is, take the time to look it up. Then, the next time you’re faced with the same situation, you’ll know what to do without much thought. If you know the rules, and you’re still unsure whether to use the comma or not, you’re probably dealing with an unclear sentence that should be recast.

  8. Kristi

    I agree completely with Sarah O’Keefe’s post about automating the formatting. It drives me up the wall to spend hours talking about manual vs. auto page breaks because an image is separated from a procedure step, for example. But I think the organization and content should still get some handcrafting. Short concise directions take longer than rambling information dumps copied and pasted from the SME’s email.
    I’ve seen writers who dump info quickly “just get it in somewhere and CYA”, and it does check things off of our department’s to-do list, but I’ve also picked up the projects after those lip-service deliveries. At times, I wonder, why even spend the time to dump the information if no one can find it, not even the people who work there?

  9. Noz

    Well… obviously I am going to agree that automatically formatting is a no-brainer, and that writers should write, not agonise over page-breaks. I in fact once burst out during a conference talk: “What is it with you people and the page breaks?”

    I wanted to chime in about the blogger. Yes, I definitely think rapid-fire blogging is best. They tend to be shorter, and only on occasion miss the point. If you do miss the point crack out another blog and link to it from the first one! I have dozens if not over a hundred blogs sitting on my hard-drive unpublished from years of ‘over-tweaking and over-thinking’. There’s a phrase regarding a pot and a certain bodily function that comes to mind…

    Tech Authors as a breed, are not the most extroverted seat-of-the-pants type folk. But that’s changing. The whole revolution in technical communication is meaning “Font Fondling” must die. We are witnessing a shift that is a scaled down version of the move to computers and the printing press from hand-crafted writing. The new shift is the move from print-based to content-based.

    Live with it.

    We lost the beauty and personality of individually crafted pages you did with a quill or a brush, but no one would go back.

  10. Rickard Lindberg

    I think you can tweak a program or a document for a very long time without ever getting satisfied. I think it is important to get it out early and get some feedback. Without feedback you can’t really be sure what to tweak.

  11. Margaret

    Tom, you really got everyone jumping in this time! I think many of us who have been doing this for a while are trying to avoid both extremes — raw and disorganized documents produced in a frenzy to get something out fast and the the over-polished, over-tweaked documents that no one reads!

    As staffs get leaner and demands increase, we have to utilize new tools and production methods that give us a reasonable middle grounds: user support and/or documentation that give users what they need to use the product to do their jobs when they get the product.

    To provide UA with the right balance, writers need good requirements, knowlede of the audience, a reasonable schedule in line with the product development schedule, and the time to develop simple templates that can be used to structure the information being filtered out of a rapidly moving development program.

    It’s analagous to an agile development program, in that if the overall program doesn’t have a solid requirements skeleton to attach all the code objects to, the product could turn into an unmanageble spaghetti tangle of incompatible pieces that don’t work together.

    We’re not asking for the moon in this economy. Just a little support to help us juggle all the pieces and do more with less.

  12. Patty

    Love the post, Tom… reminds me of what we used to call ‘Good Enough Quality’.

    Font-fondling (Am I the only who cringes at that phrase) does have its place, however… if only for establishing consistency among multiple writers on a team. If one bolds, another italicizes and a third capitalizes the same field name, doesn’t that create confusion in a profession that prides itself on doing just the opposite?

    1. Mike Starr

      Patty,

      That’s the reason all companies should have a style guide and that style guide should be incorporated into templates for whatever tool is being used. For example, if I’m using Word, I’d create a character style named “Field name” and apply it to every field name in the document. That way every field name in the document would be consistently formatted.

    2. Noz

      I actually didn’t think that that is what ‘font fondling’ was. Consistently formatting something is quiet good (and as an XML’r I find quite basic and fundamental). I understood font fondling as actually the endless massaging and tweaking of fonts or creation of endless one-off overrides because ‘this bit of information is just… special’.

  13. Craig

    Thought provoking, as usual. I never would have described myself using such words, but I am, indeed, a Duct Tape Technical Writer. I enjoy writing well-crafted, highly polished prose.

    Sometimes, however, I must bang the keyboard, produce words, make sure sentences are readable, ensure the product hangs together, and press “Publish.”

  14. Pingback: Video: Sole Writer in a Company | Save the Semicolon

  15. Pingback:   A musing on usage by Communications from DMN

Comments are closed.