Documentation is for the weak

I spent several hours reading some “documentation” today for a certain component of an enterprise product. Actually what I was doing was a repeated loop of the following:

  • Go to a page with a promising-looking title (e.g., The Fuckwidget Survival Guide)
  • Read some of the marketing-class vacuous bullshittery there, with a table of contents consisting of:
    • Overview of Fuckwidget
    • Introduction to Fuckwidget
    • Fuckwidget Operations Guide Overview
    • Fuckwidget Migration Patterns
    • Fuckwidget Introduction [didn’t we do that one already?]
    • Using Fuckwidget
    • Fuckwidget Infrastructure Templates
    • Fuckwidget for Beginners
    • Executive Guide to Fuckwidget
    • Fuckwidget Tutorial for Knuckledraggers and Mouthbreathers [didn’t we just do that one?]
    • Let’s Do Fuckwidget! (plus a crayon drawing of a cat by some VP’s kid)
    • Make Fuckwidget work for you with this One Weird Trick!
    • 10 Things You Didn’t Know about Fuckwidget
    • Fuckwidget FAQ

“Oh ho!” I whoop, and click on the promising-looking FAQ, and like a hall of mirrors I’d find myself in a document pretty much the same, but slightly different. Repeat for hours. Every time the documentation was about to admit a tidbit of actual, useful info, there was a link, and the link led to even more bullshittery.

Whereupon:

  1. Cry out “God in heaven, does any of this crap lead to any actual information about how you set up and use Fuckwidget?”
  2. Wait for an answer.
  3. No answer from God. He must be using Fuckwidget Message Queues for incoming prayers, it would explain a lot.
  4. Do another web search for “real fuckwidget documentation dear lord let it all end now” and start over.

This is an actual picture and probable copyright violation [ask me if I care] from some of that “documentation” –

plangrouppolicy

I think there’s a bug here, where they left out the part where you’re supposed to feed the security policy to a magic goat, whereupon magic shit happens that materializes into a security policy. Frankly I don’t think that anyone will be able to prove my little repurposing above, since I’m probably the first person to ever get far enough into the maze to find it.

Can we analyze this bit of art? Is it useful at all, to anyone? Well, yes, it turns out:

  1. Once upon a time there was a documentation team, on contract and paid by the hour by a large, soulless corporation that confuses quantity for quality.
  2. This team knew a good deal when they saw one, and sat in their seats and typed like crazed monkeys for as many hours as they could bill. They wrote introductions and overviews and guides and planning thingies and checklists and templates and any number of click-here-do-this-click-that instructionoids of the kind you find on really sketchy “How do I use a can-opener?” sites. The result was a massive collection of pages with a remarkable lack of useful information. And this was absolutely intentional, because:
  3. When the stone had been completely wrung dry and the documentation team could extract no more hours, the large corporation shipped the documentation out to users, and:
  4. The doc writers went back home and wrote a real reference and are happy to sell it to you for hard cash. It’s probably really popular on Amazon. I do not have the heart to search for it.

I think if I sat down for a couple of hours I could distill the documentation for this product down to about three pages, starting with an introduction like:

Hi. We know why you’re reading this, and we’re real sorry. It may help you to know that all of the suffering you are about to endure is the same suffering we went through. Of course, we had the advantage of access to the original team, so maybe we didn’t suffer quite as much. On the other hand, it may bring a smile to your face that the feedback we provided to the developers and managers was in some cases sufficiently convincing so as to ensure they will never be repeating the mistakes they made on this project. They’ll never woik in dis bidness again.

In the end, I kind-of got Fuckwidgets working. I wrote a wiki page for my coworkers with some “click here, do this-and-that” type instructions, and I feel filthy.

Bullshit triumphs when a good man does nothing.

This entry was posted in Uncategorized. Bookmark the permalink.

12 Responses to Documentation is for the weak

  1. I’m not sure this is a problem with just contract, by the hour, pubs groups. We have a 500 page document for our IDE that, after 10 pages of how to read the document (because pubs people will focus on what they love), it goes through, in deep and excruciating detail, every single feature of the product. Every menu item, every button, every configuration tab, all illustrated and described. It is a marvelous array of headers and font sizing and indentations and all the things that make a doc look “professional.”

    And it is mostly correct even, after years of revisions. The only problem is that it doesn’t tell you how to actually use our product. So I spend a good chunk of time writing cookbook articles in Notepad ++ for the people who use our product so they can actually do something with it.

    And with every release I ask when we are going to get some official how-to sort of documentation. I always get blank stares and excuses. Pubs thinks the docs look great. Sales likes the fact that it has many, many pages. Marketing is only concerned that we’re using the right logos and whatever new product naming scheme they have come up with. Management doesn’t want to waste hours on more documentation, since we have so many pages of it already. And I get stuck writing little essays on using local scoped variables or some such.

    One of the ways we haze new hires is by giving them the documentation and asking them to use the product after they have read it. Basically it is an extended version of sending somebody out for a left handed screw driver.

    • TRX says:

      I paid a lot of money for a CAD/CAM system that has *exactly* that kind of documentation. Every one of the hundreds of icons has its own description. Every menu item. But there is nothing useful about how to use the program.

      It turned out I can’t drive the program anyway. Probably 90% of its functions are icon-driven and have no menu selections. The icons are about 3/16″ or 3mm square at the resolution I run at, and most of them differ from each other only by a few pixels. There is no text option. So I can’t run the software at all.

      I paid a bunch of money for solid modeling and automatic toolpath generation, but I wound up writing G-code in a text editor anyway. Gharr…

  2. Alo says:

    Is it sad that you’ve basically describes the majority of my professional career?

    • landon says:

      Nah. If you suffer through reading my blog, you earn absolution and are not One of Them 🙂

      • Your Simian Friend says:

        Man, that’s a relief. I shudder to think of how many times I’ve committed a wad of half-baked internal documentation that represents the culmination of days of trial and effort for someone else to blindly follow later. Worse, I’ve stumbled across some of this and thought “Jeez, what moron wrote _this_”, and had to wrestle with my conscience to decide “delete it before someone else notices” and “fix it for the next poor schmuck”.

  3. C'est Moi says:

    Good technical documentation is a bit like good pop music – an anomoly which coincided with the cold war. As soon as the wall came down it all turned to shit (pardon my French). Then again maybe those writing technical documentation back in the day were better educated than wot we iz – I’m saying that as a graduate of the Derek Zoolander School for Kids Who Can’t Read Good.

    Old School lisp manuals were good, as were DEC manuals IIRC.

    • landon says:

      Long time in replying, but: For a number of years, one of my prized possessions was an early copy of the LISP Machine Moonual. It was a black one (they were color-coded).

      I didn’t have access to a real, live LISP machine, but I read that thing to tatters. Learned a lot from it.

      Later, when I did have access to LISP machines [plural!] it was my unfortunate responsibility to decommission them, so they could be sold. I never had a chance to use one for more than an hour.

      Good God, those late 70s east coast hacker manuals were gold. (I still have my DECSystem 10 manual. I can see it from here).

  4. Mike says:

    Had this exact experience this week past with Couchbase Lite for Mobile… beyond the most trivial documentation of CRUD operations, *nothing*. Hours of trawling StackOverflow, fora, etc., taught me that they have a secret, closed repository of documentation that they’ve been “thinking about opening up” for something like seven months, so far. Clearly there’s no interest in actual decent, up-to-date documentation when there’s more money in selling books and training. And this is Open Source, not some Corporate Fuckwidgetry. Open Sores is more like it.

    OTOH thankfully it is Open Source so I could clone their repositories (though that’s another Twisty Little Maze of confusopoly so that finding the *right* repo is “a bit of a challenge”) to grind through their (frequently appallingly dodgy!) source to figure things out.

    • TRX says:

      Selling books and training? They’re not serious contenders unless they have a certificate program with multiple levels! “Couchbase Gold Associate Level II?”

      Flip side: some of the best documentation I ever used was from Borland, for Turbo Pascal. By the end it had moved up to “boxed set” as the product became more complex, but it still told you what you needed to know.

  5. Jon W says:

    Good documentation exists. I think MSDN is actually, honestly, useful, even if they do their damndest to hide the good Win32 API documentation behind Visual Basic WPF HTML5 junk.

    But, yes — good documentation can only exist if there is someone who actually knows the product and actually knows what the product’s user will want in charge. That’s pretty rare.

    • As someone who waded through MSDN’s twisty little maze of poorly documented APIs for years (back when it came on CDs!), I am convinced that Microsoft had a contract with Satan Himself to write that documentation. It’s a shame that it was done this way, as the writers are already in hell and thus, can’t be sent there.

      I am also convinced that MFC came from the ninth circle of hell, where politicians and used car salesmen come from.

Leave a Reply

Your email address will not be published. Required fields are marked *