The Value of Design Documentation

Recently I asked students to tell me what kinds of requirements they start with and what (if any) design documents do they produce.Several students said that they produced documentation just because it was part of their development process. As a consequence, they felt that the documents were rarely read, were hard to keep up to date with the real code, and were expensive to generate. I know that everyone isn’t free to change their process…but if something is expensive to do and doesn’t add value, especially in this economic climate: look for a better, less expensive alternative.

My advice is to keep the precision at a low enough level that you don’t have to keep updating it with every small change. Last year I helped one client develop a 2 page high-level view of the architecture for IT applications. On the first page was a component diagram. On the back was a high-level statement of each components’ responsibilities. While during development they produced other docs, these high-level overviews were intended to orient people who were going to maintain these applications. They were pleased when this high-level view was well-received by those developers.

Simply because a tool lets you reverse-engineer an implementation into detailed class or sequence diagrams doesn’t mean you should create lots of implementation-level diagrams. On another project where we used TogetherJ, we pruned sequence diagrams (to omit detail) so that business analysts could understand the basic flow w/o having to know everything. These edited diagrams didn’t end up in any permanent design document. Instead they helped explain our working prototype.

To be effective design documents have to communicate valued information to its intended audience. So if you find yourself creating documents that aren’t useful…well, think about suggesting cost cutting and process improvement ideas to your team and management. This is the right economic climate to suggest such positive changes.

Customer service that works!

It is passe to rag on poor customer service. So I won’t. Instead I’m going to praise Interlink Electronic’s customer support. A year ago I purchased a remote pointer from Interlink. I wanted to use it on my new tablet pc. Plug-and-play didn’t work so I went to their website to read the manual which directed me to press the laser button and direct the beam on the receiver’s starburst pattern for 5 seconds to re-program the device. When the green light glows steadily the receiver is programmed to the unique address of the RemotePoint Presenter Remote. After address is established, the LED will return to blinking green.

There was no starburst pattern on the receiver and no matter how long I shined the laser on it, nothing happened. So in a fit of inspiration I sent an email to their tech support. The next morning I received a reply that said that, “my device should require no reprogramming to get it to work.” But still it ended with a polite, “are you having problems with your remote?” I replied that “yes, I was still having problems and it didn’t work.” Within an hour I got a very clear email:

Try this procedure for re-training your receiver:

1. Disconnect the receiver from the USB port and wait 10 seconds.
2. Reconnect and once the LED starts to flash, position the remote no more than a foot away from the receiver.
3. Press and hold the right arrow on the remote for about 15 seconds. You should see the flashing LED on the receiver turn to solid green, then red and back to flashing green.
4. Your remote should be good to go.

And it was. I even sent another email asking for access to downloadable software that lets you reprogram the device and I got another quick reply. I could rag on Interlink’s out of date manual or plug-and-play equipment that wasn’t. But I won’t. Because their customer service (thanks Ody) was so responsive. Helpful customer service. Imagine that.