Documentation shortcomings
in [Embedded]
|
From: Paul E. Bennett on 11 Jul 2010 18:42 D Yuniskis wrote: [%X] > 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) I can still do the hand assembly if I have to but then some of that is down to the detail checking I do when writing new functions you need to trust. > 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? I am in wholehearted agreement with you. > 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*???) There are too many places where that happens. The new guys are clueless once the knowledgeable person has moved on. Unfortunately, clients tend not to figure that you may need time to reverse engineer a component that they have already selected for inclusion and insist is used (usual symptom of getting asked to help out on projects are already in trouble and they look to someone to help pull them out of the mire). > 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... One client I worked with took this to the extreme. They had drawings for every nut, bolt and washer (type and dimension), the placement of every cable and cable clip on the machinery and views inside the junction boxes drawn to show every wire to every terminal including detail down to the text on the wire label. The protocols for communications links were very clearly shown in Time Sequence diagrams. Problems found during development were many and varied but resolved. Problems delivered to the end customer; zero. It might seem like a cost to be this details but the benefits far out-weigh that cost. -- ******************************************************************** Paul E. Bennett...............<email://Paul_E.Bennett(a)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.. ********************************************************************
From: D Yuniskis on 11 Jul 2010 20:53
Hi Paul, Paul E. Bennett wrote: > D Yuniskis wrote: > >> 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) > > I can still do the hand assembly if I have to but then some of that is down > to the detail checking I do when writing new functions you need to trust. I lost my last "hand assembler" soon after the i8080 was announced. Haven't made another, since! :> >> 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? > > I am in wholehearted agreement with you. > >> 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*???) > > There are too many places where that happens. The new guys are clueless once > the knowledgeable person has moved on. Unfortunately, clients tend not to > figure that you may need time to reverse engineer a component that they have > already selected for inclusion and insist is used (usual symptom of getting > asked to help out on projects are already in trouble and they look to > someone to help pull them out of the mire). That's one of the "tricks" you learn from experience (padding to cover those issues). Biggest problem is walking into a situation that *appears* "well documented" -- only to discover all the dox are sh*t! :< >> 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... > > One client I worked with took this to the extreme. They had drawings for > every nut, bolt and washer (type and dimension), the placement of every > cable and cable clip on the machinery and views inside the junction boxes > drawn to show every wire to every terminal including detail down to the text Ouch! But, sounds more like "visual aids" for assembly? I.e., big process control systems where the "schematic" is a hilarious understatement of the actual (miles of) wire used. > on the wire label. The protocols for communications links were very clearly > shown in Time Sequence diagrams. Problems found during development were many > and varied but resolved. Problems delivered to the end customer; zero. Finding problems on paper is *so* much easier than having to go poking around "investigating". And, usually a lot easier to *fix* (with a pen!) > It might seem like a cost to be this details but the benefits far out-weigh > that cost. I'm sure scale plays a big factor. But, regardless of scale, you still need to know what your goal is -- "deliverables" -- so you know where you are *going* and when you've *arrived*! |