Documentation shortcomings
in [Embedded]
|
From: larwe on 9 Jul 2010 15:28 On Jul 9, 3:27 pm, D Yuniskis <not.going.to...(a)seen.com> wrote: > I've been canvassing "interface specifications" for > lots of "smart instruments" over the past week. In the main, these instruments are not directly talked to by 1,000,000 end users, but by 5 vendors of data acquisition toolchains. Those 5 vendors are in constant communication with the instrument provider. The end user gets support for the toolchain from the toolchain vendor, not the instrument vendor. The documentation is not detailed because detailed documentation requires frequent updates. It IS easier and cheaper to support the 5 people they actually care about rather than the 1,000,000 people who they don't care about.
From: hamilton on 9 Jul 2010 17:35 On 7/9/2010 1:50 PM, Tim Watts wrote: > Documentation is a horrid chore. If it is divorced from the code base it > seldom gets done properly. This is why medical products cost so much. FDA says "YOU WILL DOCUMENT", or you will not sell. I can imagine what would happen to the rest of the industry is "PYFGA"(1) forced all engineers to document their work. hamilton (1) "Pick Your Favorite Government Agency" PS: I know that will never happen, I hope.
From: Paul Keinanen on 10 Jul 2010 01:09 On Fri, 09 Jul 2010 20:50:57 +0100, Tim Watts <tw(a)dionic.net> wrote: > >No one does documentation like DEC used to... The blue/red wall ... >Documentation is a horrid chore. If it is divorced from the code base it >seldom gets done properly. > >The best way IMO is to tie the documentation to the programmers (with smart >instruments, I assume the interface is talking to firmware rather than raw >hardware). > >For documenting an API to a linkable library, this is fairly trivially done >by building the documentation into the code whereby it can be auto-stripped >out and turned into something presentable. This does require the programmers >to be given guidance as to how to document stuff nicely, but it can help the >programmer IME by allowing him to concisely define an API then keep that >clear in his head while he writes code to implement it. This assumes that the programmer is at least somewhat fluent in English, which is not so obvious these days :-).
From: Paul Keinanen on 10 Jul 2010 01:47 On Fri, 9 Jul 2010 13:42:20 -0700, "John Speth" <johnspeth(a)yahoo.com> wrote: >Communication standards can go along way to relieving the manufacturer from >producing extremely detailed host int specs. The more faithful a device is >to a standard, the less support the maker will need to provide because the >programmer should be familiar with it and can additional docs elsewhere. Many standard committees would benefit from good tech writers, for instance some IEC standards are horrible, with critical information scattered around several volumes without reference or only references to several companion standards (in the apparent attempt to sell more standard documents :-). While a standard text must use carefully selected wording, but if the _reader_ must be very careful about the position of commas and perform a syntactic analysis on every sentence. Such standards would benefit a lot of some explanatory text in the same context, but apparently the standard committee members are too lazy to do it or it would require hundreds of votings about the wording of the explanatory test :-). _If_ the purpose of a standard is to improve the interoperability of systems from various vendors, the readability of the standard should be the primary concern. However, sometimes it appears that standard committees are formed so that the participants can get a way from their daily routines by keeping committee meetings in holiday resorts. In other cases, it appears that the participating companies makes the standard document so hard to interpret (comparable with patent applications) that the actual purpose is to have a closed standard between the participating companies and keeping other vendors out, but still claiming that this is an "open standard".
From: D Yuniskis on 10 Jul 2010 02:48
Hi Paul, Paul Keinanen wrote: > On Fri, 09 Jul 2010 20:50:57 +0100, Tim Watts <tw(a)dionic.net> wrote: > >> The best way IMO is to tie the documentation to the programmers (with smart >> instruments, I assume the interface is talking to firmware rather than raw >> hardware). >> >> For documenting an API to a linkable library, this is fairly trivially done >> by building the documentation into the code whereby it can be auto-stripped >> out and turned into something presentable. This does require the programmers >> to be given guidance as to how to document stuff nicely, but it can help the >> programmer IME by allowing him to concisely define an API then keep that >> clear in his head while he writes code to implement it. > > This assumes that the programmer is at least somewhat fluent in > English, which is not so obvious these days :-). Even for those claiming English as their NATIVE TONGUE! :) |