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.
- Cry out “God in heaven, does any of this crap lead to any actual information about how you set up and use Fuckwidget?”
- Wait for an answer.
- No answer from God. He must be using Fuckwidget Message Queues for incoming prayers, it would explain a lot.
- 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” –
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:
- 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.
- 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:
- 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:
- 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.