Post by thread:[OT] - Firmware Maintenance Templates/Procedures

They are not necessarily overkill. The longer I'm in this, the more documentation I want to see. Unfortunately, most of us are still not that good at it. Andy D Lloyd <spam_OUTdan.lloydTakeThisOuTGB.ABB.COM> on 06/01/2000 05:49:44 AM Please respond to pic microcontroller discussion list <.....PICLISTKILLspam@spam@MITVMA.MIT.EDU> To: PICLISTKILLspamMITVMA.MIT.EDU cc: (bcc: Andrew Kunz/TDI_NOTES) Subject: [OT] - Firmware Maintenance Templates/Procedures Hi PICsters, As we all know that documentation of code is very important and that we all *religiously* follow our procedures <cough, cough>, does anyone know of any good templates regarding maintenance as opposed to development? Such templates would ideally relate to change control procedures, bug maintenance etc. I went through the same exercise of obtaining such information for development but procedures used by the likes of NASA are a bit overkill for general embedded systems, so cut down information would be more beneficial. Any help/useful pointers would be appreciated. Kind Regards, Dan Lloyd Firmware Engineer, Electronic Operations ABB Metering. England.

Andy wrote: > >They are not necessarily overkill. The longer I'm in this, the more >documentation I want to see. > .... What's worse - seems to me - is the tendency to put everything online or on CDROM. Nice and cheap, but causes its own set of problems. It's great for databooks, where you only need to look things up occasionally, but ...... Recently, I signed onto an online business-service agency [unnamed for now] which I **should** have been able to get **started up** with mimimal effort. Unfortunately, I called the company, and they told me to register on-line and download the documentation. Well, that was about 400 pages worth of PDF files - and I didn't download everything. Then you pour thru that trying to figure out where to begin. Ever try reading 400 pages of PDF on your computer screen? For a company who everyone said was great/easy to deal with, it has turned into a real nitemare. I haven't gotten past square-1 yet with this. Also, I just bought a smallish product [the Internet Appliance described in latest Poptronics]. It has exactly **1 LINE** of documentation that says "go to our website and download the s.w.". On the site it says, download this [500KB], and then go to emware and get their s.w. [another 1-2 MB], and then go to Mchp and get MPLAB. Well, you can see what this has turned into, too. Now, if someone would just show me where home-plate is!! Moral is - there should **ALWAYS** be an easy entry into the product/system at a basic level, upon which to bootstrap off of to the more involved stuff. The more "bloat-ware" the thing is, the more important this is. My products include a 1-page text called "Getting Started", which should allow anyone to get up and running in 10 minutes. Cheers for the new way of doing business, - Dan Michaels Oricom Technologies ===================

part 0 2779 bytes content-type:application/octet-stream;Hi I agree - documentation can never be considered to be bad but it must have real value, rather than quality typical of being an "afterthought" . We do follow procedure/perform peer reviews rather than formal methods (Fagan et al) etc etc. On another documentation note, I read on the Net regarding some American University professor marking his students down for providing commented code - his argument was that you wouldn't intersperse French with English (using English to describe what the French was) because you should be fluent in the French in the first place.......Maybe the guy never had to maintain someone else's code (or he had a crystal ball)? I'll continue searching. Thanks, Dan |-------------> |(Embedded | |image moved | |to file: | |pic23996.pcx)| | | |-------------> >------------------------------------------------------------------------| |Andrew Kunz <@spam@akunzKILLspamTDIPOWER.COM> | |01/06/2000 14:54 | >------------------------------------------------------------------------| Please respond to pic microcontroller discussion list <KILLspamPICLISTKILLspamMITVMA.MIT.EDU> To: RemoveMEPICLISTTakeThisOuTMITVMA.MIT.EDU cc: (bcc: Dan Lloyd/GBPTD/ABB) Subject: Re: [OT] - Firmware Maintenance Templates/Procedures Security Level:? Internal They are not necessarily overkill. The longer I'm in this, the more documentation I want to see. Unfortunately, most of us are still not that good at it. Andy D Lloyd <spamBeGonedan.lloydspamBeGoneGB.ABB.COM> on 06/01/2000 05:49:44 AM Please respond to pic microcontroller discussion list <TakeThisOuTPICLISTEraseMEspam_OUTMITVMA.MIT.EDU> To: RemoveMEPICLISTTakeThisOuTMITVMA.MIT.EDU cc: (bcc: Andrew Kunz/TDI_NOTES) Subject: [OT] - Firmware Maintenance Templates/Procedures Hi PICsters, As we all know that documentation of code is very important and that we all *religiously* follow our procedures <cough, cough>, does anyone know of any good templates regarding maintenance as opposed to development? Such templates would ideally relate to change control procedures, bug maintenance etc. I went through the same exercise of obtaining such information for development but procedures used by the likes of NASA are a bit overkill for general embedded systems, so cut down information would be more beneficial. Any help/useful pointers would be appreciated. Kind Regards, Dan Lloyd Firmware Engineer, Electronic Operations ABB Metering. England. Content-type: application/octet-stream; name="pic23996.pcx" Content-Disposition: attachment; filename="pic23996.pcx" Attachment converted: creation:pic23996.pcx (????/----) (00016015)

part 0 3737 bytes content-type:application/octet-stream; He's not too swift. My mother and her family came to America from Germany in 1951. They speak German to one another most of the time, but often they mixed English words without skipping a beat. Since most Western programming languages are English-based, it makes sense to put comments in your native tonque, whatever that may be. At least you'll be better able to understand your own code then. I have a Russian friend who comments in English, because "technical English is just very bad Russian" (referring to the Greek root of both technical languages) and "nutting is lost in the translation." Andy D Lloyd <dan.lloydEraseME.....GB.ABB.COM> on 06/01/2000 12:03:57 PM Please respond to pic microcontroller discussion list <EraseMEPICLISTMITVMA.MIT.EDU> To: RemoveMEPICLISTEraseMEEraseMEMITVMA.MIT.EDU cc: (bcc: Andrew Kunz/TDI_NOTES) Subject: Re: [OT] - Firmware Maintenance Templates/Procedures Hi I agree - documentation can never be considered to be bad but it must have real value, rather than quality typical of being an "afterthought" . We do follow procedure/perform peer reviews rather than formal methods (Fagan et al) etc etc. On another documentation note, I read on the Net regarding some American University professor marking his students down for providing commented code - his argument was that you wouldn't intersperse French with English (using English to describe what the French was) because you should be fluent in the French in the first place.......Maybe the guy never had to maintain someone else's code (or he had a crystal ball)? I'll continue searching. Thanks, Dan |-------------> |(Embedded | |image moved | |to file: | |pic23996.pcx)| | | |-------------> >------------------------------------------------------------------------| |Andrew Kunz <RemoveMEakunzspam_OUTKILLspamTDIPOWER.COM> | |01/06/2000 14:54 | >------------------------------------------------------------------------| Please respond to pic microcontroller discussion list <RemoveMEPICLISTTakeThisOuTspamMITVMA.MIT.EDU> To: EraseMEPICLISTspamspamBeGoneMITVMA.MIT.EDU cc: (bcc: Dan Lloyd/GBPTD/ABB) Subject: Re: [OT] - Firmware Maintenance Templates/Procedures Security Level:? Internal They are not necessarily overkill. The longer I'm in this, the more documentation I want to see. Unfortunately, most of us are still not that good at it. Andy D Lloyd <RemoveMEdan.lloydKILLspamGB.ABB.COM> on 06/01/2000 05:49:44 AM Please respond to pic microcontroller discussion list <PICLISTSTOPspamspam_OUTMITVMA.MIT.EDU> To: spamBeGonePICLISTSTOPspamEraseMEMITVMA.MIT.EDU cc: (bcc: Andrew Kunz/TDI_NOTES) Subject: [OT] - Firmware Maintenance Templates/Procedures Hi PICsters, As we all know that documentation of code is very important and that we all *religiously* follow our procedures <cough, cough>, does anyone know of any good templates regarding maintenance as opposed to development? Such templates would ideally relate to change control procedures, bug maintenance etc. I went through the same exercise of obtaining such information for development but procedures used by the likes of NASA are a bit overkill for general embedded systems, so cut down information would be more beneficial. Any help/useful pointers would be appreciated. Kind Regards, Dan Lloyd Firmware Engineer, Electronic Operations ABB Metering. England. Content-type: application/octet-stream; name="pic23996.pcx" Content-Disposition: attachment; filename="pic23996.pcx" Attachment converted: creation:pic23996.pcx 1 (????/----) (00016019)

Dan Lloyd wrote: .......... >On another documentation note, I read on the Net regarding some American >University professor marking his students down for providing commented code - >his argument was that you wouldn't intersperse French with English (using >English to describe what the French was) because you should be fluent in the >French in the first place.......Maybe the guy never had to maintain someone >else's code (or he had a crystal ball)? > Having had some experience both in and out of the university, and having seen this sort of perfessor upcloseandpersonal, I can note that: - many of them believe in the concept of "self-documenting" or "self-commenting" code. - many of them believe computer scientists don't do programming. - many of them have never actually done much coding. - the ivory tower is not the real world. - experience counts. - never beat a dead horse. Regarding the 1st [and worst] item, this idea is usually taught in Pascal101 [ie, CS101], where much of the code comes out looking more like a book [ie, prose] than a program. This is supposed to be more natural for the beginner. Most people versed in C, I think, look at this kind of output with horror. Cheers, - "the once and never ghost of pascal past"