Jaime Gago Condensing Information Systems From the Vapor Of Data


Angry -Technical Documentation- Nerd

Sa-potpourriToday while exploring another revolutionary-ultra-scalable-and-easy-to-setup tool  I decided the amazing-and-incredible amount of gobbledygook I found on that page justified a post, albeit a short one.

As a "systems guy" I spend a lot of my professional time deploying and/or reusing code/tools somebody else wrote, my point being reading technical documentation is a second nature. It then seems logic to think I'm a target of such docs and so here is for the feedback loop...


While I understand the technical folks can't always be in control of the front pages (which I typically read diagonally anyway),  repeated superlatives highly stimulate my BS senses when they continues on the technical areas.

I understand you mean to be informative, and you really think your application is "easy to setup" (and it probably is) but then we're in tech doc land, a place where we all know how relative "easy to setup" is.

Give me numbers, specs, examples

Instead of "fast", give me a benchmark (bonus points if -objectively- compared to similar software)

Instead of "easy to setup", give me a time to install with the underlying specs (bonus points for a link to video)

Instead of going with "will scale beyond the thousands of nodes", give me a link to a study case where such a scale has been reached.

The culprit

Found on a single -walkthrough- page

"powerful multitasking system that can solve many specific problems in an infrastructure... provides an extremely fast, flexible and easy to use configuration management system... not only amazingly easy to set up and use, but also capable of solving very complex problems in infrastructures... has been made to be very easy to install and get started..."






Comments (1) Trackbacks (0)
  1. I concur. The marketing hyperbole causes my eyes to glaze in the same way, as I’ve seen, my tech-speak makes non-techies eyes frost over. I don’t get worked up about the gobbledygook however, I simply use it as a clear marker in any documentation that “this section can be skipped”.

Leave a comment

No trackbacks yet.