Engineers push for better documentation

March 09, 2015

karen.field-March 09, 2015

Everyone benefits from good documentation. So why does so much of it suck, and how can companies do better?

Early in his career, Chris Svec, a senior principal software engineer at iRobot, was trying to figure out why some code worked the way it did. “There were some really complicated function calls or something like that, and it just didn’t make any sense to me,” he recalled.

Combing through prior versions of the code for any information that might provide a clue, he silently cursed the jerk that had left a crumbless trail. And then he realized that the jerk was — yours truly.

Sound familiar?

“We all understand that good documentation is important and we would all like it to be better, but unfortunately it’s very easy to convince yourself you can put off doing a better job — or even doing it at all — since it’s not a hair-on-fire situation,” said Svec.

The fact that documentation is important but not urgent, makes it an all-to-easy thing to kick down the road with the sincerest of intentions to get back to it later. But when that doesn’t happen, it becomes the next guy’s (or girl’s) problem.

And next time that person just might be the “future you.”

This master pinout diagram for the open source Spark Core Wifi Module, created not by the designer but by a community member, may well be among the best hardware documentation on the planet.
This master pinout diagram for the open source Spark Core Wifi Module, created not by the designer but by a community member, may well be among the best hardware documentation on the planet.

(Click here to see a larger image.)

The thing is, everyone knows good documentation when they see it. Svec points to the master pinout diagram for the Spark Core Wifi Module (shown above) as quite possibly the best hardware documentation he’s ever seen.

[LEARN ABOUT OSHW TOOLS, INCLUDING THE SPARK CORE: at ESC Boston]

To read more of this external content, go to "Engineers on Creating Better Technical Documentation."

 


Join over 2,000 technical professionals and embedded systems hardware, software, and firmware developers at ESC Boston May 6-7, 2015, and learn about the latest techniques and tips for reducing time, cost, and complexity in the development process.

Passes for the ESC Boston 2015 Technical Conference are available at the conference's official site, with discounted advance pricing until May 1, 2015. Make sure to follow updates about ESC Boston's other talks, programs, and announcements via the Destination ESC blog on Embedded.com and social media accounts Twitter, Facebook, LinkedIn, and Google+.

The Embedded Systems Conference, EE Times, and Embedded.com are owned by UBM Canon.

Loading comments...

Most Commented