Several years back, my colleagues at IONA shipped some product samples with a new version of the Orbix product to demonstrate how to use encryption and other security features. We used some self-signed SSL certificates that would expire a few years after the product’s ship date, and in the documentation we clearly specified that those certificates were for demonstration purposes only and they should be replaced with the organization’s own certificates.
One morning, some years after shipping that demo with the product, the phone started to ring. A lot. Angry emails quickly started to fill the inboxes of our support staff. We soon learned that a very large and reputable organization had an Orbix system in production that was suddenly having major problems and showing “all sorts of security errors.”
This customer had constructed a business-critical system using the sample code as a starting point and had never followed the advice in the documentation to use their own SSL certificates. They screwed up, but the incident points to a few larger lessons about how software vendors should treat their own product’s samples.
Lesson #1 – Assume your product’s samples will go into production
Once your customers feel satisfied enough by running your samples to believe that they work correctly, it’s highly likely that some of those samples will form the basis of your customer’s future production code. I’ve done this, and I know plenty of others who comfortably do the same. Starting development from a sample is a reasonable springboard when learning a new technology.
Be absolutely sure that your samples don’t contain any memory leaks, race conditions or optimistic assumptions that might not always be valid. If they do, expect to see those problems flow right back into your company via the support lines in the not-too-distant future.
Lesson #2 – Don’t assume your customer will read your sample’s documentation
Your customers are most likely neither dumb nor lazy. But they are almost certainly incredibly busy. That means that they’ll play with your samples by firing up a build and running them immediately, so if you’re expecting them to read reams of documentation before they do that, you’re kidding yourself. The only customers who might read your sample’s documentation will be those few who have problems running the sample correctly and have enough patience that they don’t give up on your product at the first sign of trouble.
So, if you have a really important message about a particular sample (such as the one described above about SSL certificates) you should make it appear as part of the sample itself. Sure, put it in the documentation too – but make the sample spit out that message every time it’s run so that your customers cannot miss it.
Lesson #3 – Use best practices in every sample
Since you wrote your product, you’re considered to be the expert on it. So it’s hardly a leap to think that there will be an astonishing amount of “copy and paste” used by your customers when they’re starting work with it. Therefore, if there’s a particular pattern or usage style that you’d like to promote (or discourage, for that matter), your samples are the best places to begin that effort.
Now if you’ll excuse me, I have a few samples to play with. And perhaps to deploy into production.
More Than Coding 