Documentation shortcomings

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.

larwe wibbled on Friday 09 July 2010 20:28

No one does documentation like DEC used to...

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.

For device firmware, it might not be so obvious, unless each function maps

1-1 to a device subroutine. But I assume there is a way to logically tie a piece of code to a documentation system so that when someone changes the code, they can link over to the relevant bit of documentation and update that (via a revision control system of course).

All of this does require forethought and planning and assigning a priority to documentation from the get-go and put a system in place, which I'm realistic enough to realise just doesn't happen in some companies either because they are crap, or because they are little and are trying to be first to market with something or else they die.

Cheers

Tim

--
Tim Watts

Managers, politicians and environmentalists: Nature's carbon buffer.

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.

hamilton wibbled on Friday 09 July 2010 22:35

Although the point I was trying to make is that there are degrees of horridness.

I didn't find it in the least bit tedious to POD document a load of perl modules I wrote commercially - because I wrote a little preamble in POD to each public API stating parameters (with ranges if required), return value and what happens on an error. And a paragraph on what it did which was semi obvious from the method name anyway. And I wrote that before I wrote a single line of code for that API because it clarified what I was trying to do and what bounds needed to be checked.

What I did find yuk was documenting a server with a network API because there wasn't such an obvious way of doing it and it essentially boiled down to maintaining a parallel document. I'm sure there must be methodologies for this sort of thing... It's all about how procedurally easy (or not) it is. If that's sorted out up front (like "thou shalt use Doxygen everywhere in your libraries") then it's not really a burden at all.

If it's "be sure to document it" it never gets done until someone asks to see it, then it's bashed out in a hurry and full of errors...

--
Tim Watts

Managers, politicians and environmentalists: Nature's carbon buffer.

The blue/red wall ...

This assumes that the programmer is at least somewhat fluent in English, which is not so obvious these days :-).

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".

Well, I like to think *I* do! ;-)

The problem lies in considering documentation as a separate activity. How do the *developers* (hardware, software, marketeering, etc.) know what the hell they are *developing*? Aren't their documents describing what they *think* the product is intended to be?? (*gasp* -- specifications???)

Somewhere, the developer has to "know" what he's trying to write. If everything is "ad lib", then you get crap for reliability, etc. ("Gee, Bob quit yesterday. Tom will be taking over the project. I wonder what *he* thinks he'll be developing??")

I just can't comprehend that. Just like not *testing* products before release, etc. If you're too small to afford those "luxuries", when will you have the time to go *back* and do them? How will you counter the folks who claim "why should we do it for

*this* project? we didn't do it for the *last* project!"?

If you can't afford to be in that business, go into some *other*.

Exactly. Otherwise you have no way of knowing where you are going with the design (unless it's a "toy"/trivial design).

But where were the design documents that *drove* the server's implementation? How did "whomever" decide that the server met its intended goals? Or, was it just a case of, "We've spent enough money on this; let's move on to something else..."?

The example I was citing infers that the documentation I seek exists, somewhere -- "Call the factory". So, someone has codified it -- even if it is on the back of a coffee-stained napkin. What is the cost to replace the *bad*, incomplete description of the interface with the *correct* description from that napkin?

E.g., one of the scales I interface to has three pages describing the serial communication protocol. Incompletely.

Here's the commentary that I #include in the lex(1) and yacc(1) specifications for my parser (I've had to trim line length for my NNTP client). It's *briefer* than the vendor's literature (one page instead of three) and addresses all of the issues that

*should* have been addressed (though written from the standpoint of a particular consumer and implementation)

-----------8

So, how do they get the information they need -- phone calls?? (seems an expensive way of providing that information!)

Consider the examples I mentioned: these are devices for which the "interface" is almost as important as the "sensor" itself. I.e., we're not talking about adding a serial port to a dishwasher. Rather, it's a device whose sole purpose is to provide sensory data to another "electronic device" (computer, printer, etc.). Presumably, you *expect* people to be using that interface (indeed, many devices have no *other* way of getting their data to the user -- "displayless"!)

And, AFAICT, these interfaces are *very* static. I don't see lots of firmware revisions documented, etc. I suspect (but haven't gone looking for corroborative evidence) that these manufacturers have multiple similar product offerings and probably reuse the same interface ("standards") between them. I.e., time spent documenting one could probably server *others* as well.

Remember, "you" (in this case) is a piece of code. Sure, a human being examining a message stream could probably garner the needed data from that stream. But, doing so algorithmically and in a manner that is *guaranteed* to ALWAYS work without some formal specification of the message format is a crap shoot.

Is "0" expressed as "00000.00"? "0.00"? "0."? "0"? Can you ever encounter *minus* zero? Is 1/2 expressed as "00000.50"? "0.50"? "0.5"? ".5"? Is 1/8 expressed as 0.12 or 0.13? What about -1/8? 7/8?? How are units conversions handled? Is any accuracy gained (or lost) based on the units of measurement selected for use in the interface?

All of these are easy questions for a developer to answer (assuming he knows his product). And, none require any serious/detailed explanation to present in unambiguous terms.

Even for those claiming English as their NATIVE TONGUE! :)

D Yuniskis wibbled on Saturday 10 July 2010 07:12

Abysmal lack of testing and lack of documentation is more common than you would want to imagine - especially in the UK (something to do with our world famous management and excellent work ethic?[1]) (irony).

I know of places so s**te that they:

a) Never run a formal backup.

b) Next to no documentation on anything.

c) No email infrastructure despite having a domain - everyone communicates with customers using own personal email addresses (how very professional).

d) No version control systems of any description. Not even a policy.

[1] They only reason we had a sod-off massive Empire was because half the world only had pointy sticks.

--
Tim Watts

Managers, politicians and environmentalists: Nature's carbon buffer.

No, I can *imagine* that. I just can't *comprehend* it. I.e., it just doesn't make sense from a practical standpoint.

Bugs cost a *lot* more to fix (orders of magnitude) "post-release".

Answering email/snailmail/phone inquiries ("support") costs far more than pro-actively answering those questions with good documentation.

And, none of this even tries to quantify the cost to reputation, etc. in the marketplace as customers get fed-up/disgruntled with your products (its a lot harder to *get* a customer than it is to *keep* a customer).

The argument that "everyone is doing it" doesn't wash, either. Here's a way to *excel* and capture greater market share and/or command higher prices for your products. So, you'd rather live with the market share that falls into your lap and the prices that the *market* dictates??

I suspect you will find most developers are guilty of this. Even the ones who's livelihood *depends* on that "vulnerable data". "Wow, I *never* expected a crash..." (um, what about an OS bug, controller failure, computer falling onto floor, *theft*, *fire*...)

But then how do they know what they are building/designing? Or, do they just *hope* it "makes sense" (as a product) once it is "done"? (how do they know it is "done"?)

Yeah, this one always amuses me. Or a web site that is "single sheet thin"...

I have worked with pharma, etc. suppliers who cringed when they were held to task on these sorts of issues. I guess they expected "Trust Us" to be a good business policy...

... and dull rocks.

Given how easy it is to outsource *much* of this work, nowadays, one would think these other issues would be a great way to add-value that was *hard(er)* to outsource. E.g., manuals written by people who actually are conversant (not even *fluent*!) in English (gasp).

I am not so sure if this reduces the support requests these days, but at least with good documentation you can refer to RTFM xx.yy page nn:-).

Even with a good documentation set, a search engine targeting the actual manuals only (no press releases etc :-) would help finding any usable information in many cases.

Googling is often the fastest way of finding the useful information from a large document set (rather than going the manual tree at the web site). This works OK for publicly available documents, but for internal documents or extranet (for actual customers only) documents, such engines are not always available.

Yes, but you have to *prepare* that documentation (or, publish the documentation that you have *previously* prepared).

If you are going to have to *eventually*, by *some* means, make that information available to the user/customer (i.e., even if that is forwarding an inquiry to the *developer* who looks through his code -- because he doesn't have any OTHER documentation for how his code is *supposed* to work!), then why not do so to start with?

Since I've been just talking about technical information, you can argue that it doesn't need to be "dumbed down" for a non-technical person's perusal. E.g., the owner's manual for your car doesn't provide detailed valve timing information; but, the service manual for the *auto techs* does (and it doesn't have to waste lots of text explaining how the valves work to admit intake air, vent exhaust gases, etc.)

Good point ------------^^^^^^^^^^^^^^^^^

(why do companies think folks are interested in their market-speak?)

world

Which is still better than finding out it is on some hidden FAQ document, or some application note which is not referenced from anywhere else and has a title that is in internal speak.

e.g. "How to do xx with product range 'Turbo widget wangler'"

When the product range you are looking at is "Wibbling anchovies".

There are a few manufacturers that are 'good' at that for silicon.

Yes the referencing and search facilities are only as good as the consistent naming policy.

I am reminded of one product over 20 years ago that referred to a group of switches on one board by THREE different names in the

circuit diagram user manual test programme

Often internal serach engines only search title and short description not the whole document.

--
Paul Carpenter          | paul@pcserviceselectronics.co.uk
    PC Services
 Timing Diagram Font
  GNU H8 - compiler & Renesas H8/H8S/H8 Tiny
 For those web sites you hate

Because the people controlling the web sites, are usually marketing and investor relations, so they think the ONLY people who visit the web site are investors and the press. Products and actual sales/support information is way down the list or has to be with login after NDA exchange.

Do you remember the NXP website relaunch which meant it was difficult to get into the NXP site to even find a product about a year ago.

Too often i have had to do NDA exchange to get information that is less than a datasheet, more a product brief.

--
Paul Carpenter          | paul@pcserviceselectronics.co.uk
    PC Services
 Timing Diagram Font
  GNU H8 - compiler & Renesas H8/H8S/H8 Tiny
 For those web sites you hate

I learnt early on in my apprenticeship years the value of the production of a decent Technical Specification and a decent Interface Control Document (ICD). Between those two documents you have the whole story about what the device is, what it does, and how you interface to it in mechanical, electrical and protocol terms.

I tend to ask for these documents if they are not supplied and often find that the supplier is lacking them. If you make it a condition of the sale then they produce something quickly that is never entirely accurate and all of this costs time and effort. I produce such documentation as part my normal development process (being employed in the arenas I am) and I know that my clients expect me to do so. I would be so out of work if any of what I delivered was not up to scratch.

--
********************************************************************
Paul E. Bennett...............
Forth based HIDECS Consultancy
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************

Exactly! Imagine designing a bit of *hardware* with a document that describes a component as little more than "Microcomputer, 13 bit" (without a pinout, package diagram, instruction set details, opcode timings, etc.)

"Oh, well... the ADD opcode is only intended to be used when the two arguments are '1' and '2', respectively. Otherwise, the answer is incorrect (i.e., '3')"

Even if the documents don't exist, it is usually *much* smarter to invest the time yourself preparing them to drive *your* part of the design process (I've sold documentation back to clients where it didn't exist previously -- in a sense, they end up paying me

*twice* for it!)

In some industries/markets, this is SOP. The *process* is *as* important as the result.

But, once you've worked with documentation "up front" (regardless of its origin), it's almost impossible to go back to working without it! (sort of like trying to go back to "hand assemblers" when you've worked with HLL's)

Returning to my original gripe... these devices (instruments) exist for the sole purpose of interfacing to other devices. That is an essential aspect of what they *are*. So, the information describing these interfaces *must* exist somewhere else no one would use them. Why have two sets of documents? A published one that is incomplete and inaccurate and another "crib sheet" hiding in the back of the developer's drawer? (what happens when "Bob" quits?? Will you know what *your* product *does*???)

Always have lots of fancy detailed CAD drawings showing you the size of any panel cutouts, thread pitch of the screws used to mount it, etc. -- things that damn near anyone could obtain empirically with a dial caliper. Yet, the BFM within the box remains shrouded in a mist...