Basic documentation - is it too much to ask for? -

Basic documentation — is it too much to ask for?

I've pondered the topic of various forms of documentation on several occasions over the years; for example, do you recall my Error messages we can all understand diatribe and my Different Countries = Different Writing Styles in User Manuals discussions?

As an aside — and I know I've dropped this tidbit of trivia into the conversation before — I always find user manuals that are written in Israel to have a very Shakespearean “feel” to them. (I was moved to mention this because the 400th anniversary of Shakespeare's death will be April 23, 2016, which is tomorrow as I pen these words.) When you are reading an Israeli manual, you can almost imagine two characters on the stage, where the first exclaims “'But where are the variables?' you ask,” and the second responds in a deep bass voice “Why, the variables are over here!” But we digress…

The reason for this column is that I was recently introduced to a really cool piece of technology — a magical module I would love to use in my hobby projects — but its creators focused only on the hardware and left the documentation simmering away on the back burner with a “We'll get round to that before we ship the product,” philosophy.

Well, guess what — they are now shipping the product with documentation that can best be described as “minimalistic” (some might say “non-existent”).

The thing is that this is not an isolated incident. I've seen it happen over and over again as the sands of time have slipped through my personal hourglass.

Why, Oh why, do companies get themselves into this pickle? Don’t they realize that providing even rudimentary documentation will make everyone's lives easier? Also that the time and resources they will end up using to support the product will be inversely proportional to the quality of the documentation they supply?

What say you? Have you run across this sort of thing yourself, or is it just me?

12 thoughts on “Basic documentation — is it too much to ask for?

  1. “These past few days I've been tearing my hair out over ST's woeful lack of documentation for the STM32 series and the software libraries that come with it. The MCU series, and the STM32Cube tool, seems to have an awful lot of nice features. It's just that

    Log in to Reply
  2. “Recently, I was on a team that was working to bring up a board with a programmable power sequencer IC. We had used the manufacturers PC software to generate a program but couldn't get it on the chip without the custom script that someone in our company wr

    Log in to Reply
  3. “I think you're on to something here — as you say, things are obsolete almost as soon as they are released. I remember when I worked for Intergraph in the late 1990s — we would submit a new computer for review in print magazines, but they had a 3+ month

    Log in to Reply
  4. “On the one hand I'm thinking “Thank goodness that it's not just me,” and on the other hand I'm thinking “Why is it this way?””

    Log in to Reply
  5. “It can get even worse: documentation for features that don't really work.nI'm using this biometric processor that can be communicated with by UART or SPI. We bought the development kit and it worked pretty well with its UART interface, it only was too sl

    Log in to Reply
  6. “OMG — this is the sort of thing we all dread and hope will never happen to us.nnI could tell you some stories — but then again I can't because I've been sworn to secrecy.”

    Log in to Reply
  7. “IMHO it is simple. In a consumer market if a product is defective or the manual useless the customer (not technically savvy) simply returns the product, gives the seller a hard time, and often writes a scanting review about the product that spreads throug

    Log in to Reply
  8. “I was actually horribly mislead by my first real contact with datasheets. Back in the day when I first started programming microcontrollers I didn't have internet, I was borrowed a book on how to programm Microchip's PIC16 microcontroller in assembler, wh

    Log in to Reply
  9. “I do agree — the datasheets of yesteryear tended to be WAY better than those of today — although I have to say that NXP have got a couple of really good ones”

    Log in to Reply

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.