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?”
“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
“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
“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
“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
“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.”
“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
“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
“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”
You must verify your email address before signing in. Check your email for your verification email, or enter your email address in the form below to resend the email.
Please confirm the information below before signing in.
{* #socialRegistrationForm *}
{* firstName *}
{* lastName *}
{* displayName *}
{* emailAddress *}
By clicking "Sign In", you confirm that you accept our terms of service and have read and understand privacy policy.
{* /socialRegistrationForm *}
Almost Done
Please confirm the information below before signing in. Already have an account? Sign In.
“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
“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
“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
“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?””
“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
“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.”
“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
“So at the end of the day it's our fault … the way my day is going that sounds about right LOL”
“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
“Fortunately this experience hasn't left you bitter in any way LOL”
“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”
“NXP also have some datasheets that aren't very good. I think it depends on what division created the part”