Hi All,
I would much rather not spend any time on a Friday night ranting about computer stuff, but today I had enough reading this crap.
There is something about embedded developers and stinky documentation that seem to go hand-in-hand.
What's the deal with this?
The culprit, in this case, is Atmel.
I am reading page 334 of their 800+ page datasheet for their AT91SAM9260.
On it is a diagram of how their GPIO/peripheral system is supposed to work.
First, I guess to help readers without EE background, they use their own special symbols for signal selectors/buffers. Then, as if they forgot the reason for using their own symbols, they throw in a few buffers. They should have simply used standard buffer symbols.
The chapters regarding clocks and timing are piss poor. It's almost as if the writer, not being comfortable in English, decided to stick to pictures only. In several places, the key sequence of words that an experienced electrical engineer or software engineer would be looking for are missing. It's maddening.
The paragraph of section 28.4.5 about how to synchronize a bank of GPIO signal transitions is unintelligible. I think that a non-native English speaker wrote it after using an on-line translator.
Guys (or Gals)... C'mon...unless you are *fluent* in English,
STOP PUBLISHING THIS STUFF!!!
IT'S ANNOYING TO THE PEOPLE WHO ACTUALLY SPEAK ENGLISH.
And I am sorry: Using a 14-point Helvetica theme does not a good document make.
ATMEL. You're a big company. You can afford a native English speaker with a technical background to proof-read your documents. Get one. It's simple. After you finish writing the document, just have this person run through it and clean it up.
Sometimes I wish I spoke Chinese, so I could reciprocate the obnoxiousness of writing in a language that I have not mastered, knowing that my target audience consists of native speakers of that language. And no, I do not single out the Chinese. I am speaking of every situation where this happens, whether it is Hindi, Russian, etc.
And Atmel is not the only guilty party.
SiLabs, for an app not for programming flash, gives wrong index for device ID register. They also show a flow chart as a guide for the programmer which inverts two of the steps.
STM? Their documents are full of comma splices, like the one in this sentence, they could write better.
Comma splices seem to be more and more common among technical people, as if their is an unspoken rule that it is no longer correct to make two complete sentences.
Note that I am not complaining about casual sloppiness in writing from time to time. There's nothing wrong with that. A quick review of my USENET posts will reveal numerous spelling errors. What I am complaining about is professional documentation that makes you wonder if the author has proper bathroom habits.
Of course, if you are individual non-native speaker just trying to do your best, none of this applies to you.
I am talking about multi-billion-dollar corporations.
Clean up your product!
-Le Chaud Lapin-