Embedded Muse 133 Copyright 2006 TGG September 6, 2006

EDITOR: Jack Ganssle, jack@ganssle.com

CONTENTS:
- Editor’s Notes
- Preserving Design Decisions
- Tools
- Jobs!
- Joke for the Week
- About The Embedded Muse

Editor’s Notes

TV chef Emeril is always “kicking things up a notch” by adding garlic and other zestiness to his recipes. How are your firm’s engineering recipes? Want to kick up your development processes by more than a notch? I can present my Better Firmware Faster class at your facility. See https://www.ganssle.com/classes.htm .

The Embedded Systems Conference will be in Boston September 25-28. It’s always an interesting and fun event. I’m giving three talks. Some 150 exhibitors will be showing off their latest offerings. I’ll be wandering the show floor; stop me and say “hello.”

Preserving Design Decisions

I know he had agonized over the $300 purchase, his engineering attitude wanting to ensure the radio was the best possible value for the money. We were with our families well outside of the USA with no email access and phone service priced out of sight for support calls. The manual documented quite a few error messages, but strangely not this one.

Sound familiar? A year earlier my autopilot stopped steering. It sounded three short beeps, paused, and then one more before repeating the pattern over and over. Clearly this was some sort of diagnostic code, one not listed in the manual, and one that tech support couldn’t identify. “Send it in for repair” was the oh-so-standard response to all such unknown embedded systems behaviors.

Yet surely the firmware engineers went to a lot of trouble to put these exception conditions into the code. They mean something; but that meaning was lost due to poor documentation. Why bother detecting and reporting the condition when users will be baffled?

It’s easy to tell the programmers to log everything they do, and to hope that the documentation and customer support folks will turn these notes into useful web FAQs and manual addendums. But that’s tough. Developers are busy enough trying to fulfill requirements and work out system bugs. Creating a support doc in parallel just ain’t gonna happen, perhaps unless one has an always-available tool where it’s easy to make notations. In a collaborative environment the best tool is probably a wiki, coupled with training and an iron will to log everything we learn.

Maybe we need a documentation scavenger. Someone empowered to dig through the code looking for things that impact the customer. A person that bridges the development, support, and doc teams.

Or perhaps, if we’re wise enough to be doing code inspections, one of the inspectors is always a customer/documentation representative. If you’re using eXtreme Programming, where a pair of developers share one computer, the person not typing could capture each of these new exceptions and ensure they’re emailed to the doc team.

Some might insist that at requirements time we know all of the error codes and other intricacies of the system. In my experience, though, during coding we discover – and write code to trap - odd cases that should never happen, or that we’d hope would never happen. A three level deep IF can resolve into an awful lot of possible conditions, far more than we usually anticipate until we’re deep into the unit design or code. That’s when a lot of the error messages and exception handlers get written, and that’s where they get lost to the customers.

I do remember committing the same sin early in my career. Our instrument solved a very complex series of simultaneous polynomials using an iterative algorithm. (And this was on an 8008!). At times no solution was possible, so I’d programmed it to give up after 20 minutes and display “Help” on the 7 segment LEDs. Years later, long after the device was obsolete and most of the original staff dispersed to other companies, a unit came back for repair. The young technician appeared at my office door, ashen. He had been adjusting internal pots when the machine started flashing “help” messages. He thought some intelligence inside the box was reacting to his repair attempts…

What do you think? How can we pass the critical error messages created by our exception handlers into useful customer artifacts?

Tools

Another tip for those who haven't found it yet is to add Notepad (or your favourite text editor) to the Send To list. Just create a shortcut to the editor in Documents and Settings\{USER}\SendTo. That way you can view any document type as text directly from a right click.

Christopher Meisenzahl wrote: I'm always on the lookout for a great, free text editor, and I've tried many. ;-)

My current favorite is this one. Pretty small, can be easily scripted, and allows column editing! http://www.context.cx/

Jobs!

Joke for the Week