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”
We use cookies on our website to give you the most relevant experience by remembering your preferences and repeat visits. By clicking “Accept All”, you consent to the use of ALL the cookies. However, you may visit "Cookie Settings" to provide a controlled consent.
This website uses cookies to improve your experience while you navigate through the website. Out of these, the cookies that are categorized as necessary are stored on your browser as they are essential for the working of basic functionalities of the website. We also use third-party cookies that help us analyze and understand how you use this website. These cookies will be stored in your browser only with your consent. You also have the option to opt-out of these cookies. But opting out of some of these cookies may affect your browsing experience.
Necessary cookies are absolutely essential for the website to function properly. These cookies ensure basic functionalities and security features of the website, anonymously.
Cookie
Duration
Description
cookielawinfo-checkbox-analytics
11 months
This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional
11 months
The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary
11 months
This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others
11 months
This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance
11 months
This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy
11 months
The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.
Functional cookies help to perform certain functionalities like sharing the content of the website on social media platforms, collect feedbacks, and other third-party features.
Performance cookies are used to understand and analyze the key performance indexes of the website which helps in delivering a better user experience for the visitors.
Analytical cookies are used to understand how visitors interact with the website. These cookies help provide information on metrics the number of visitors, bounce rate, traffic source, etc.
Advertisement cookies are used to provide visitors with relevant ads and marketing campaigns. These cookies track visitors across websites and collect information to provide customized ads.
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”