RANT: Embedded Devlopers And Stinky Documentation

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.

formatting link

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-

Reply to
Le Chaud Lapin
Loading thread data ...

On Sep 16, 10:48=A0pm, Le Chaud Lapin wrote: [snip]

Sigh. I had to do a quick look-up for Keil/C++, and what pops up in my face?

A *(@$% run-on sentence right in the middle of the home page:

"Keil C51 is the industry-standard toolchain for all 8051-compatible devices, it supports classic 8051, Dallas 390, NXP MX, extended 8051 variants, and C251 devices."

It also supports engineers who do like run-on sentences.

-Le Chaud Lapin-

Reply to
Le Chaud Lapin

It is not so recently emergent as a phenomena. I have been in the engineering business for 42 years and have had this sort of thing crop up on numerous occasions throughout my career. There is not enough time in the day to deal with each and every little typo, spelling error or mis-guidance that appears in the documents you may view. You just end up dealing with the items that affect your immediate problem.

I do, however, agree with you that documentation should be consistently coherent, well structured and correctly informative. Something that I strive for in all of my own work.

--
********************************************************************
Paul E. Bennett...............
 Click to see the full signature
Reply to
Paul E. Bennett

I can live with stilted or awkward writing, it's the correctness that sometimes make me shake my head. The description of the CAN peripheral for a CM3 chip from a major manufacturer was simply wrong in three places in a Revision 2 user's manual. Set it up by the book and it will not work. It can be an interesting and challenging intellectual exercise to figure these things out but that's not what pays the bills. The "Aha!" moment can be a lot of fun, tho. ;-)

--
Rich Webb     Norfolk, VA
Reply to
Rich Webb

I wouldn't be so sure. Sometimes it's schools and sometimes also parents. Seriously.

Doesn't look too bad. You should try some Asian datasheets :-)

"When value change blue is pin up" and things like that.

You mean the thing about the unexpected transient values?

Why? Ok, I use Times New Roman but what's wrong with Helvetica?

^^^^^^^^^^^^^^^

Oh-oh ...

The long sentences are popular in some northern European countries so if the chip was designed there it can happen. Cut them some slack there, think about the comma as a soldering joint :-)

To be honest, this one doesn't look too bad to me. At least not compared to many Asian datasheets. But I do see a trend and usually with native speakers: Typos, grammar, writing style, all that is seriously heading down the tubes the younger the writer is. Even for people with a serious academic background. That is so sad. Besides schools and parents there's probably another reason: Texting. "dude" ... "wassup" ... "notn" ... "cool" ... "by".

--
Regards, Joerg

http://www.analogconsultants.com/
Reply to
Joerg

I've read /huge/ numbers of datasheets and technical documentation throughout my career, and I would not single out this datasheet as being at all bad. I fail to see any non-standard symbols. Their use of enable, disable and status register sets is a little unusual, but once you've understood that, it's clear what these sets of three bit names on the diagram do. The multiplexers, logic gates and buffers are all standard. As for section 28.4.5 that you mentioned, I see no language mistakes other than a few poor choices of prepositions ("in" and "at" instead of "to"), which are common among native speakers. I certainly didn't have trouble understanding it on one read - and I'd never looked at an AT91SAM datasheet before now.

There are lots of bad datasheets out there. If you've ever tried to look at LCD display documentation, it is traditionally written in Japlish - English words, but Japanese grammar. And I once had to work with a German ASIC whose English manual was apparently translated from the original by someone with little grasp of either German or English languages, and absolutely no technical knowledge of the device. One entire chapter was replaced by the sentence "Original German unclear" !

In my experience, Atmel do quite a good job of their documentation. I can't think of any cases where their datasheets have been wrong or have lacked information I needed, and it's all been reasonably easy to find. Certainly there are many other companies - some bigger than Atmel - who do a much worse job.

Reply to
David Brown

The only thing I can think of is that it is common practice to use serif fonts for the main text of a document - the serifs help the eye flow along the line. Sans-serif fonts are more commonly used for headers, or particular typographical effects.

However, for a datasheet or other reference document, it is not nearly as important to use a serif font. You don't normally read through the text in the way you would when reading prose, and you read it more slowly anyway. So I see no harm in sans-serif here.

I also note that the datasheet in question had quite wide margins (for the body text), and a relatively large font. That means fewer words per line, which is easier to read, and plenty of space which is nice for making notes on printed copies. The typesetting could be improved by better line and page breaks (the "0x0" starting a line, but ending the paragraph, is particularly poor), but the font choice is fine (IMHO).

Reply to
David Brown

Hmmm... why then do you rant about the quality of documentation that _other_ people prepare for embedded developers to _use_?

Or maybe it's just a natural change. All human languages evolve over time, and that includes technical jargon. Terms you and me learned may have gone completely out of fashion since.

Well, as the saying goes: something's gotta give. The price most people are prepared to pay for a well-edited datasheet is: ZERO. Sometimes you do get what you pay for.

The bigger the company, the more bean-counters you get. Those guys just _love_ to veto any expenses. They'll block any effort that might lift documentation quality above "just barely acceptable".

Are you 100%, positively _sure_ you would rather have no datasheet at all, instead of one written in questionable grammar?

Reply to
Hans-Bernhard Bröker

Whole National Semiconductors or Unitrode books are written sans serif. But for published books you are right. Art of Electronics and my bible (the real one) are written in a serif font.

They should also increase the left general margin by 50-100%. Some people (like myself) might print out a chapter and file it into a binder at least during a project. That can occasionally cause the hole punch to eat part of a section number.

--
Regards, Joerg

http://www.analogconsultants.com/
Reply to
Joerg
[much elided]

Your complaints, below, seem to be geared towards *suppliers*, not "developers".

Actually, *if* the writer isn't comfortable in the language, I much *prefer* a drawing -- assuming that drawing is *accurate*. Textual descriptions often omit lots of detail. And, often that detail is the stuff that bites you in the end ("Gee, do I load this counter with 'N' or 'N-1'?")

Perhaps, instead, they should stop making their parts available to the English-speaking market? That would surely solve *your* problem...

+42

But, I wouldn't single out any *one* vendor. Many (most?) are guilty of this, to some degree. Or, have a writer who isn't fluent with the *technology*

I suspect you haven't written many *big* technical documents (i.e., *hundreds* of pages with dozens of pages of index, etc.). The "6th grade writing style" just doesn't work for big documents. And, if you have ever tried to *read* a document written at that level of UNsophistication, you would quickly throw your hands up in frustration. You end up writing a clumsy paragraph where a (lengthy, complex) sentence will instead, suffice.

Documentation is expensive. Documentation is often underappreciated. Documentation represents yet another "thing" that has to be maintained (in addition to the silicon, software, packaging, etc.). The attitude tends to be one of "necessary evil" -- vendors would rather find a couple of *huge* customers that they can bring up to speed (even if that means giving them access to the actual *designers* of the devices) than cater to hundreds of "little fish".

Often, documentation is prepared by "junior" staff. It gives them exposure to a product line before they actually can inflict *harm* on "product". It acts as a rite of passage in many institutions... you pay your dues and then "move up" to the Big Leagues. The "Designer Elite" don't want to be bothered with those boring details, etc.

Consider, also, that documentation is often NOT prepared by the individual(s) that *designed/conceived* the device. These third parties have to *infer* what the design philosophy might have been, rationalize inconsistencies in the design, etc. *And* try to present it to someone who may have absolutely *no* experience with this device or even devices of this *type*.

I am a *huge* believer in documentation. I suspect almost half of my job involves some form of documentation activity -- writing specifications, documenting design criteria (as well as my actual design choices), test cases and the rationale behind them, user manuals, service guides, etc.

Figure out who *your* "documentation customers" are (actual customers, manufacturing staff, support staff, your future self, etc.). Then, think about what they are saying about *your* documentation. Does it answer ALL of their needs? Do they have to talk to you for clarification on specific items? Does your documentation reflect the

*current* state of your work? Or, some past state (possibly even *partially*)? Could someone approach your "product" (whether that is a piece of code or a piece of FR4) *cold* and correctly make even a *simple* change? Or, would they spend a disproportionate amount of time looking for information that *should* be "obvious"?
Reply to
Don Y

Keil C51 is a toolchain. It is the industry standard toolchain for all 8051-compatible devices. It supports classic 8051. It supports Dallas 390. It supports NXP MX. It supports extended 8051 variants. Also, it supports C251 devices.

Run, Spot, run!

And, it's not just "datasheets". Technical books, references, etc. are not immune.

I found some really tiny (2 sq in?) Post-It notes many years ago and *scoffed* at them. "Who the hell would use *these*? They're so tiny you can bearly write anything on them!" I now rely on them extensively for annotating books, etc. (I dislike marking up the original -- esp if I later discover an error in *my* markup)

+42

Give me a flow chart, schematic diagram, etc. and, assuming *it* has no errors, I can figure out what you *wanted* to say.

I found that it often pays to express something in two different forms. Not only does this give readers a choice of how they want to "take in" the information (e.g., some folks are more graphically oriented so a drawing speaks louder to them than a paragraph of text would), but, it also gives an opportunity to catch errors in *your* presentation/description: "The text says 'Preload the counter with N' but the equivalent schematic diagram clearly shows that you need to load it with -N!"

For code sequences I have found that the most reliable way of including them in a document is *literally* to #include them into the document. This ensures there are no typos, missing punctuation, etc.

Reply to
Don Y

p on

day

that

rive

I've also seen a lot of bad writing, poor grammar and downright incomprehensible datasheets; mostly from Asian manufacturers. It's slightly annoying, and I might have to read it over a few times to understand what they're saying, but it's not a showstopper. What really gets me is documentation that's spread out over five or six separate documents, located in at least as many different places on the manufacturer's website. One document with a product overview, another with a feature spec, another for a reference manual, another for a register summary, and another for electrical specifications. This can really be a good time waster trying to find them all.

What's really bad is documentation that's downright incomplete. Registers or bits that are implemented in the chip but not documented (and I don't mean "reserved" or test registers), min/max voltage levels and currents that are not specified (am I supposed to figure it out myself through destructive testing? Send more samples!) and datasheets with tables filled in with TBD (another reel of samples please!)

Reply to
Stimpy

{%X]

I thought I had been all-inclusive by using the term "the documents you may view" But I agree, it is not just the data-sheets. It is the web-sites, the app-notes, the data-sheets, the tech-books (written by the company and others) where these errors of omission or commission may creep in.

Yes, they are very useful at times.

However, if it had errors you would have to work harder to figure out the intentions. The big question is when would you be able to spot those errors.

Several views of the same thing are always helpful to spot any errors. If all views lead to the same conclusions it, at least, will be consistently right or consistently wrong.

Always good practice when such inclusion is necessary.

--
********************************************************************
Paul E. Bennett...............
 Click to see the full signature
Reply to
Paul E. Bennett

I haven't, yet, been able to come up with a mechanism -- formal or otherwise -- of chasing down references to "stuff" that might creep over multiple -- possibly unrelated -- documents. I.e., I currently rely on simple *memory* to recall when some change I'm making to will require some *other* document (possibly dealing with ) to also be revised to reflect this change.

And, the number of documents that *I* have to keep track of pales by comparison with a large organization. I suspect this also contributes to errors and inconsistencies.

Yes. But, give me *more* data to evaluate, rather than less. If you only provide me with an outline instead of "detail", then I have a harder time determining when I have encountered an error in that document -- I have to give you the benefit of the doubt in those "unspecified details" (else pester you for *all* of those issues).

OTOH, if you provide ample detail -- however terse -- I can invest the time to discover flaws in your documentation. Or, flaws in the product itself. ("Hmmm... what happens if I set X to 0? Does '0' mean zero? Or, MAXINT+1?")

It can also bring attention to design aspects that need rethinking. E.g., if you are representing something as a code sequence and find that code littered with conditionals, you should probably step back and ask yourself if this "mechanism" can't be designed more simply -- eliminating all of these special cases!

I don't understand why this isn't done more often! I suspect one problem is folks who just compose them and never really

*verify* that they work.

If I am having a problem with a tool, the first thing I do is find any "examples" that the vendor has supplied and I verify their functionality (whether it is a piece of code or a sample application). If this doesn't work, then I contact the vendor -- "I'm having problems with your product. It isn't working for me the way I expect it to work. Furthermore, I've tried using *your* example and it doesn't work the way *you* expected it to work, either!"

Granted, the problem might be something trivial. But, having something that the vendor provided as a reference ("talking point") quickly removes "me" from the equation -- "No, it's not a bug in my code/design... since it is present in *yours* as well!" I find having done this before contacting a vendor for support gets me around the first level of "dismissals" that they tend to throw in your way: "Have you rebooted your machine?" "Yes, followed by a clean install of *just* the OS and *your* toolchain. Don't even *think* of blaming some *other* piece of software running on my host! Now, are you ready to help me figure out what *your* problem is, here?"

Reply to
Don Y

Imprecavo contro il nuovissimo ordinamento quando Joerg ha detto :

not only in norhtern European countries. In Italian (and all Latin based languages) it's horrible to see something like "I speak Italian. I speak English. I speak Spanish". Talking or writing like that would make you look like a retarded. "I speak Italian, English and Spanish" is the only right form to express that concept. Anyway...right use of commas is one of the most difficult concepts in Latin based languages.* They are not meant to build long sentences but to give pauses, correlate sentences or list ideas

Reply to
N1

Agreed. However, if you were to "grade" the reading level of this set of statements, you would find it targets the "correct" complexity level intended for most writing (e.g., "6th grade" -- about 11 years old).

One could assume that technical documents are most often read by a "more educated" audience. Yet, you still have to consider how easy it is for *any* reader -- even one technically inclined -- to tackle complex grammar while simultaneously trying to deal with a new technical concept, etc.

E.g., it's akin to balancing parens in LISP. More punctuation and sentence structure requires more effort for the reader to keep track of what belongs with what.

I try to write like I would *speak* to a person when describing a concept, implementation, etc. -- except to avoid colloquialisms. The punctuation should impart a good "rhythm" to the reading that corresponds to the same type of rhythm you would encounter in the spoken word.

Reply to
Don Y
[...]

[...]

as others wrote, this Atmel document isn't so bad. You have to learn to ignore style weakness.

Real errors will break your application, and I found many of those in data sheets from different manufacturers.

But the more annyoing problem is that many companies don't even correct errors when you report them.

I would like to know whether first level support doesn't forward corrections or other parties are ignoring them.

Oliver

--
Oliver Betz, Munich
despammed.com is broken, use Reply-To:
Reply to
Oliver Betz

You know, I wonder if a wiki wouldn't make sense in a "commercial" environment? I.e., have the vendor create Rev. 0 of the document. Then, let *users* tweek it to reflect REALITY!

Or, would there be legal/liability ramifications that would scare vendors away from this approach?

Shark: Isn't it true that documentation posted on your corporate web site contained this misinformation which led my client to design a faulty product which eventually resulted in the deaths of four people? Vendor: Yes, but that document is "user maintained" and has a clear disclaimer to that effect present on ALL pages. Furthermore, to gain entry to the site, users (including your client) are required to sign a release acknowledging this. Shark: But do you have staff that routinely monitor the web site in question? For example, to remove any disparaging comments about your company, the quality of its products, etc.? Vendor: Well, yes, but... Shark: So, someone at your company was undoubtedly aware of the presence of this incorrect information on that site yet chose to do nothing about it?

Reply to
Don Y

I find the Atmel documentation to be more readable than datasheets from some other manufacturers.

OTOH, I really don't like it when they document a feature in detail and then a couple of hundred pages later bury a single paragraph in the middle of the errata that says this feature doesn't fully work reliably on many of the part's revisions.

(This in reference to the USART hardware handshaking mode on the SAM7S series, BTW. You can lose a character if the incoming CTS line changes state at just the wrong time during a small window.)

I'm about to find out. I've found what appears to be a conceptual level problem in the CTS handling when the SAM7S USART is run in modem mode. (This is different from the problem above.)

At first I thought I must be missing something (given how popular the part is and the fact I was still learning the part at the time) so I contacted Atmel support with my analysis and the response I got agreed that it's a real problem. I've asked them to pass it to the documentation people (which they say they have done) for inclusion within the datasheet.

It will be interesting to see if anything comes out of my request.

Simon.

--
Simon Clubley, clubley@remove_me.eisner.decus.org-Earth.UFP
Microsoft: Bringing you 1980s technology to a 21st century world
Reply to
Simon Clubley

That is (or, at least, was) a scary thing in a corporate environment. Way back when in Honeywell Information Systems, some Level-6 minicomputer support guys in Australia put together a support forum on the corporate network where techs inside the company could confer and help each other out. I was reading it in Toronto. It was fascinating stuff and it only lasted a couple of months.

Lack of a clear control/responsibility structure was probably an issue too: q.v. one of the later episodes of _The Office_ where printers were catching fire.

Mel.

Reply to
Mel

ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.