Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
RANT: Embedded Devlopers And Stinky Documentation
21 views
Skip to first unread message
Le Chaud Lapin
Sep 16, 2011, 11:48:34 PM9/16/11
to
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.
http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
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-
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.
http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
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-
Le Chaud Lapin
Sep 17, 2011, 1:36:40 AM9/17/11
to
On Sep 16, 10:48 pm, Le Chaud Lapin <jaibudu...@gmail.com> wrote:
[snip]
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-
[snip]
> 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.
Sigh. I had to do a quick look-up for Keil/C++, and what pops up in my
> as if their is an unspoken rule that it is no longer correct to make
> two complete sentences.
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-
Paul E. Bennett
Sep 17, 2011, 4:06:16 AM9/17/11
to
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...............<email://Paul_E....@topmail.co.uk>
Forth based HIDECS Consultancy
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************
Rich Webb
Sep 17, 2011, 8:33:04 AM9/17/11
to
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
Joerg
Sep 17, 2011, 10:47:48 AM9/17/11
to
Le Chaud Lapin wrote:
> 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 wouldn't be so sure. Sometimes it's schools and sometimes also
> 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.
>
parents. Seriously.
> I am reading page 334 of their 800+ page datasheet for their
> AT91SAM9260.
>
> http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
>
"When value change blue is pin up" and things like that.
> 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
Oh-oh ...
> two complete sentences.
>
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 :-)
> 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!
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/
David Brown
Sep 17, 2011, 10:56:12 AM9/17/11
to
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.
David Brown
Sep 17, 2011, 11:39:20 AM9/17/11
to
On 17/09/11 16:47, Joerg wrote:
> Le Chaud Lapin wrote:
> Le Chaud Lapin wrote:
>> And I am sorry: Using a 14-point Helvetica theme does not a good
>> document make.
>>
>
> Why? Ok, I use Times New Roman but what's wrong with Helvetica?
>
>
The only thing I can think of is that it is common practice to use serif
>> document make.
>>
>
> Why? Ok, I use Times New Roman but what's wrong with Helvetica?
>
>
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).
Hans-Bernhard Bröker
Sep 17, 2011, 3:28:42 PM9/17/11
to
On 17.09.2011 05:48, Le Chaud Lapin wrote:
> There is something about embedded developers and stinky documentation
> that seem to go hand-in-hand.
Hmmm... why then do you rant about the quality of documentation that
> There is something about embedded developers and stinky documentation
> that seem to go hand-in-hand.
_other_ people prepare for embedded developers to _use_?
> the key sequence of words that an experienced electrical engineer or
> software engineer would be looking for are missing. It's maddening.
time, and that includes technical jargon. Terms you and me learned may
have gone completely out of fashion since.
> Guys (or Gals)... C'mon...unless you are *fluent* in English,
>
> STOP PUBLISHING THIS STUFF!!!
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?
Joerg
Sep 17, 2011, 3:39:57 PM9/17/11
to
David Brown wrote:
> On 17/09/11 16:47, Joerg wrote:
>> Le Chaud Lapin wrote:
>
>>> And I am sorry: Using a 14-point Helvetica theme does not a good
>>> document make.
>>>
>>
>> Why? Ok, I use Times New Roman but what's wrong with Helvetica?
>>
>>
>
> 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.
>
Whole National Semiconductors or Unitrode books are written sans serif.
> On 17/09/11 16:47, Joerg wrote:
>> Le Chaud Lapin wrote:
>
>>> And I am sorry: Using a 14-point Helvetica theme does not a good
>>> document make.
>>>
>>
>> Why? Ok, I use Times New Roman but what's wrong with Helvetica?
>>
>>
>
> 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.
>
But for published books you are right. Art of Electronics and my bible
(the real one) are written in a serif font.
> 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).
>
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.
Don Y
Sep 17, 2011, 6:57:50 PM9/17/11
to
On 9/16/2011 8:48 PM, Le Chaud Lapin wrote:
[much elided]
> There is something about embedded developers and stinky documentation
> that seem to go hand-in-hand.
Your complaints, below, seem to be geared towards *suppliers*, not
"developers".
> 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.
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'?")
> 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.
Perhaps, instead, they should stop making their parts available to
the English-speaking market? That would surely solve *your* problem...
> 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.
+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*
> 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.
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.
> 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!
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"?
[much elided]
> There is something about embedded developers and stinky documentation
> that seem to go hand-in-hand.
"developers".
> 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.
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'?")
> 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.
the English-speaking market? That would surely solve *your* problem...
> 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.
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*
> 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.
(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.
> 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!
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"?
Don Y
Sep 17, 2011, 7:08:33 PM9/17/11
to
Hi Rich, Paul, etc.
On 9/17/2011 5:33 AM, Rich Webb wrote:
> On Sat, 17 Sep 2011 09:06:16 +0100, "Paul E. Bennett"
> <Paul_E....@topmail.co.uk> wrote:
>
>> Le Chaud Lapin wrote:
>>
>>> On Sep 16, 10:48 pm, Le Chaud Lapin<jaibudu...@gmail.com> wrote:
>>> [snip]
>>>> 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.
>>>
>>> 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."
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!
>>> It also supports engineers who do like run-on sentences.
>>>
>>> -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.
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)
>> 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.
>
> I can live with stilted or awkward writing, it's the correctness that
> sometimes make me shake my head.
+42
Give me a flow chart, schematic diagram, etc. and, assuming *it*
has no errors, I can figure out what you *wanted* to say.
> 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. ;-)
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.
On 9/17/2011 5:33 AM, Rich Webb wrote:
> On Sat, 17 Sep 2011 09:06:16 +0100, "Paul E. Bennett"
> <Paul_E....@topmail.co.uk> wrote:
>
>> Le Chaud Lapin wrote:
>>
>>> On Sep 16, 10:48 pm, Le Chaud Lapin<jaibudu...@gmail.com> wrote:
>>> [snip]
>>>> 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.
>>>
>>> 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."
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!
>>> It also supports engineers who do like run-on sentences.
>>>
>>> -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.
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)
>> 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.
>
> I can live with stilted or awkward writing, it's the correctness that
> sometimes make me shake my head.
Give me a flow chart, schematic diagram, etc. and, assuming *it*
has no errors, I can figure out what you *wanted* to say.
> 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. ;-)
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.
Stimpy
Sep 18, 2011, 12:12:39 AM9/18/11
to
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!)
Paul E. Bennett
Sep 18, 2011, 6:48:18 AM9/18/11
to
Don Y wrote:
> Hi Rich, Paul, etc.
>
> On 9/17/2011 5:33 AM, Rich Webb wrote:
>> On Sat, 17 Sep 2011 09:06:16 +0100, "Paul E. Bennett"
>> <Paul_E....@topmail.co.uk> wrote:
>>
{%X]
> Hi Rich, Paul, etc.
>
> On 9/17/2011 5:33 AM, Rich Webb wrote:
>> On Sat, 17 Sep 2011 09:06:16 +0100, "Paul E. Bennett"
>> <Paul_E....@topmail.co.uk> wrote:
>>
>>> 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.
>
> And, it's not just "datasheets". Technical books, references, etc.
> are not immune.
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.
> 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)
>>> 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.
>>
>> I can live with stilted or awkward writing, it's the correctness that
>> sometimes make me shake my head.
>
> +42
>
> Give me a flow chart, schematic diagram, etc. and, assuming *it*
> has no errors, I can figure out what you *wanted* to say.
intentions. The big question is when would you be able to spot those errors.
>> 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. ;-)
>
> 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!"
all views lead to the same conclusions it, at least, will be consistently
right or consistently wrong.
> 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.
Don Y
Sep 18, 2011, 9:38:42 AM9/18/11
to
Hi Paul,
On 9/18/2011 3:48 AM, Paul E. Bennett wrote:
>>>> 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.
>>
>> And, it's not just "datasheets". Technical books, references, etc.
>> are not immune.
>
> 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.
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
<foo> will require some *other* document (possibly dealing with <bar>)
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.
>>>> 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.
>>>
>>> I can live with stilted or awkward writing, it's the correctness that
>>> sometimes make me shake my head.
>>
>> +42
>>
>> Give me a flow chart, schematic diagram, etc. and, assuming *it*
>> has no errors, I can figure out what you *wanted* to say.
>
> 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.
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?")
>>> 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. ;-)
>>
>> 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!"
>
> 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.
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!
>> 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.
>
> Always good practice when such inclusion is necessary.
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?"
On 9/18/2011 3:48 AM, Paul E. Bennett wrote:
>>>> 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.
>>
>> And, it's not just "datasheets". Technical books, references, etc.
>> are not immune.
>
> 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.
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
<foo> will require some *other* document (possibly dealing with <bar>)
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.
>>>> 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.
>>>
>>> I can live with stilted or awkward writing, it's the correctness that
>>> sometimes make me shake my head.
>>
>> +42
>>
>> Give me a flow chart, schematic diagram, etc. and, assuming *it*
>> has no errors, I can figure out what you *wanted* to say.
>
> 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.
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?")
>>> 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. ;-)
>>
>> 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!"
>
> 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.
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!
>> 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.
>
> Always good practice when such inclusion is necessary.
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?"
N1
Sep 18, 2011, 3:25:01 PM9/18/11
to
Imprecavo contro il nuovissimo ordinamento quando Joerg
<inv...@invalid.invalid> ha detto :
<inv...@invalid.invalid> ha detto :
> 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 :-)
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 <-- oh yes, like this :)
* I could have used a comma there.
--
"Non � mai troppo tardi per imparare a suonare..."
"S� bh�, magari alle 3 di notte evita."
Don Y
Sep 18, 2011, 4:30:34 PM9/18/11
to
On 9/18/2011 12:25 PM, N1 wrote:
> Imprecavo contro il nuovissimo ordinamento quando Joerg
> <inv...@invalid.invalid> ha detto :
>
>> 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 :-)
>
> 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
> Imprecavo contro il nuovissimo ordinamento quando Joerg
> <inv...@invalid.invalid> ha detto :
>
>> 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 :-)
>
> 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
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.
> 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<-- oh yes, like this :)
Actually, I find use of semicolon and dash to be more problematic.
All punctuation affects the pauses -- or inflection -- in our speech.
Technical people also tend to break rules, subtly. E.g., your:
'In Italian (and all Latin based languages) it's horrible to see
something like "I speak Italian. I speak English. I speak Spanish".'
should actually be:
'In Italian (and all Latin based languages) it's horrible to see
something like "I speak Italian. I speak English. I speak Spanish."'
I think this a consequence of our thinking of quotes in the same
"matched sense" as parens (this was a poor example to cite).
Oliver Betz
Sep 19, 2011, 5:20:39 AM9/19/11
to
Le Chaud Lapin wrote:
[...]
>http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
[...]
>STOP PUBLISHING THIS STUFF!!!
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:
[...]
>http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
[...]
>STOP PUBLISHING THIS STUFF!!!
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:
Don Y
Sep 19, 2011, 7:45:41 AM9/19/11
to
Hi Oliver,
On 9/19/2011 2:20 AM, Oliver Betz wrote:
> 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.
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?
Simon Clubley
Sep 19, 2011, 9:04:22 AM9/19/11
to
On 2011-09-19, Oliver Betz <ob...@despammed.com> wrote:
> Le Chaud Lapin wrote:
>
> [...]
>
>>http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
>
> [...]
>
>>STOP PUBLISHING THIS STUFF!!!
>
> 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.
>
I find the Atmel documentation to be more readable than datasheets from
> Le Chaud Lapin wrote:
>
> [...]
>
>>http://www.atmel.com/dyn/resources/prod_documents/doc6221.pdf
>
> [...]
>
>>STOP PUBLISHING THIS STUFF!!!
>
> 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.
>
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.)
> 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.
>
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
Mel
Sep 19, 2011, 10:12:10 AM9/19/11
to
Don Y wrote:
> 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?
That is (or, at least, was) a scary thing in a corporate environment. Way
> 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?
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.
Stef
Sep 19, 2011, 10:40:17 AM9/19/11
to
In comp.arch.embedded,
Interesting indeed, let us know what happened.
My experience with Atmel is not good on this point. Years ago, I found
an error in a datasheet. Very minor error: reverse bit function
description. Took lots of mails and them sending me sample-code (which
did not use the bit, probably because it did not work as the datasheet
said) before they agreed the datasheet was wrong. They then said the
change would be in the next revision. That revision came after a long
time and did not include the change. When I asked them about it, they
could not explain why it wasn't included and said it will be in the
next release. Still awaiting that release ...
--
Stef (remove caps, dashes and .invalid from e-mail address to reply by mail)
Reactor error - core dumped!
My experience with Atmel is not good on this point. Years ago, I found
an error in a datasheet. Very minor error: reverse bit function
description. Took lots of mails and them sending me sample-code (which
did not use the bit, probably because it did not work as the datasheet
said) before they agreed the datasheet was wrong. They then said the
change would be in the next revision. That revision came after a long
time and did not include the change. When I asked them about it, they
could not explain why it wasn't included and said it will be in the
next release. Still awaiting that release ...
--
Stef (remove caps, dashes and .invalid from e-mail address to reply by mail)
Reactor error - core dumped!
Don Y
Sep 19, 2011, 11:02:07 AM9/19/11
to
Hi Mel,
On 9/19/2011 7:12 AM, Mel wrote:
> Don Y wrote:
>> 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?
>
> 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.
So, this was a "private" forum. I.e., presumably, customers weren't
exposed to it, no danger of corporate secrets leaking *out*, etc.
> I was reading it in Toronto. It was fascinating stuff and it only lasted a
> couple of months.
One has to wonder if shutting it down wasn't more of a reaction to
"how *dare* you guys do something without our explicit approval?
(i.e., behind our back)"
> 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.
Dunno "The Office".
I suspect in any organization where the lawyers have a loud voice,
this would be "strongly discouraged" (they don't *really* want to
have to WORK for their pay when they can, instead, collect it while
doing reasonably safe things -- like telling you NOT to take any
chances...).
I wonder how companies that (ahem) "support" public forums address
the liability issue? I.e., what's the difference between folks
posting questions on a "user forum" (sponsored by the company)
vs. "marking up a wiki"?
On 9/19/2011 7:12 AM, Mel wrote:
> Don Y wrote:
>> 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?
>
> 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.
exposed to it, no danger of corporate secrets leaking *out*, etc.
> I was reading it in Toronto. It was fascinating stuff and it only lasted a
> couple of months.
"how *dare* you guys do something without our explicit approval?
(i.e., behind our back)"
> 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.
I suspect in any organization where the lawyers have a loud voice,
this would be "strongly discouraged" (they don't *really* want to
have to WORK for their pay when they can, instead, collect it while
doing reasonably safe things -- like telling you NOT to take any
chances...).
I wonder how companies that (ahem) "support" public forums address
the liability issue? I.e., what's the difference between folks
posting questions on a "user forum" (sponsored by the company)
vs. "marking up a wiki"?
Oliver Betz
Sep 19, 2011, 12:07:56 PM9/19/11
to
Stef wrote:
[...]
>My experience with Atmel is not good on this point. Years ago, I found
>an error in a datasheet. Very minor error: reverse bit function
>description. Took lots of mails and them sending me sample-code (which
>did not use the bit, probably because it did not work as the datasheet
>said) before they agreed the datasheet was wrong. They then said the
>change would be in the next revision. That revision came after a long
>time and did not include the change. When I asked them about it, they
>could not explain why it wasn't included and said it will be in the
>next release. Still awaiting that release ...
same procedure at Freescale.
First it takes a lot of effort to convince them, then it doesn't help
anything.
I gave up.
[...]
>My experience with Atmel is not good on this point. Years ago, I found
>an error in a datasheet. Very minor error: reverse bit function
>description. Took lots of mails and them sending me sample-code (which
>did not use the bit, probably because it did not work as the datasheet
>said) before they agreed the datasheet was wrong. They then said the
>change would be in the next revision. That revision came after a long
>time and did not include the change. When I asked them about it, they
>could not explain why it wasn't included and said it will be in the
>next release. Still awaiting that release ...
First it takes a lot of effort to convince them, then it doesn't help
anything.
I gave up.
Paul
Sep 19, 2011, 6:31:30 PM9/19/11
to
In article <jtpe77lrm8cre5cvg...@z1b.oliverbetz.de>,
ob...@despammed.com says...
In my experience, it can take a LONG time for the information to go up
and down the chain.
A few years back a collegue and me noted a discrepancy in a vode
processing, we reported the problem for 18 months later the rep to
tell us the problem.
If you get close enough contact with manufacturers engineering or top
level support sometimes it works. On one I sae a revision of datasheet
within two months with TWELVE extra pages and improved diagrams.
Mainly depends how close to the source you are when reporting problems.
--
Paul Carpenter | pa...@pcserviceselectronics.co.uk
<http://www.pcserviceselectronics.co.uk/> PC Services
<http://www.pcserviceselectronics.co.uk/fonts/> Timing Diagram Font
<http://www.gnuh8.org.uk/> GNU H8 - compiler & Renesas H8/H8S/H8 Tiny
<http://www.badweb.org.uk/> For those web sites you hate
ob...@despammed.com says...
and down the chain.
A few years back a collegue and me noted a discrepancy in a vode
processing, we reported the problem for 18 months later the rep to
tell us the problem.
If you get close enough contact with manufacturers engineering or top
level support sometimes it works. On one I sae a revision of datasheet
within two months with TWELVE extra pages and improved diagrams.
Mainly depends how close to the source you are when reporting problems.
--
Paul Carpenter | pa...@pcserviceselectronics.co.uk
<http://www.pcserviceselectronics.co.uk/> PC Services
<http://www.pcserviceselectronics.co.uk/fonts/> Timing Diagram Font
<http://www.gnuh8.org.uk/> GNU H8 - compiler & Renesas H8/H8S/H8 Tiny
<http://www.badweb.org.uk/> For those web sites you hate
Joerg
Sep 19, 2011, 9:06:08 PM9/19/11
to
N1 wrote:
> Imprecavo contro il nuovissimo ordinamento quando Joerg
> <inv...@invalid.invalid> ha detto :
>
Depends on which law. Ok, there are some that I do curse ... :-)
> Imprecavo contro il nuovissimo ordinamento quando Joerg
> <inv...@invalid.invalid> ha detto :
>
>> 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 :-)
>
> 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 <-- oh yes, like this :)
>
>
> * I could have used a comma there.
>
language and they did not allow us to learn real Italian or Spanish
instead. Now I really regret that because where I live I could really
use Spanish.
Dave Nadler
Sep 21, 2011, 4:52:00 PM9/21/11
to
My favorite was an LCD controller doc that showed
the sequential steps required for each operation
across the page. The Janglish wasn't too horrid,
but unfortunately the sequences were carefully
translated to English but shown right-to-left
on the page as appropriate for Japanese...
Wasted more than a day figuring that one out !
YMWV,
Best Regards, Dave
PS: "Standard" in which country ???
the sequential steps required for each operation
across the page. The Janglish wasn't too horrid,
but unfortunately the sequences were carefully
translated to English but shown right-to-left
on the page as appropriate for Japanese...
Wasted more than a day figuring that one out !
YMWV,
Best Regards, Dave
PS: "Standard" in which country ???
Joerg
Sep 24, 2011, 4:06:11 PM9/24/11
to
short sentence, basically saying that the unit has a reset and where
there control line for that is. So we issued a reset to test this out
... *PHOOMP* ... after the windows were opened and the smoke cleared out
we found that their idea of a reset consisted of a relay that shorts the
5V rail. We had a 5V/100A switch-mode supply ...
0 new messages