Understand the Difference Between Demos and Code Examples
Lots of technology products and platforms aimed at developers — possibly the majority of them — confuse the distinction between a good demo and a good code example. A good demo looks great and dazzles your CEO and customers. On the other hand, good code examples seem to take forever to write, they never look good and they can’t be installed on the demo machine at trade shows to dazzle prospective customers.
There is a fundamental difference between a demo and a code example.
Even when a demo is available as downloadable source code, it often
doesn’t work as a good code example.
No platform in the history of platform technologies has ever devoted enough resources to creating code examples. One of the best-documented platforms I know (Microsoft’s .NET framework) still contains plenty of objects and methods that don’t have code examples anywhere. But doing this is part of the tax you have to pay if you want to have a platform. You can either do this, or you can write all the applications that you ever want to run on your platform by yourself — your pick.
Not having any documentation or code examples at all is a big problem, but using demos as code examples can be an even bigger problem because it forces developers to invest a ton of time into painstakingly picking out the code example bits from your demo. If you don’t have any code examples at all, it saves me time, because I know immediately that your product or platform isn’t ready yet and I’ll just check back in a few months.
Here are the differences between demos and code examples.
A good demo:
- Provides information about cutting-edge or new functionality of your platform
- Demonstrates the functionality and usefulness of your technology or platform
- Appears presentable and is well designed
- Can be appreciated by coders as well as non-coders
- Is available as source code
- Is intended to get users to adopt or purchase your product
A good code example:
- Provides information about the existing functionality of your platform
- Must function and run out of the box with as little configuration as possible
- Must not have invisible or undocumented dependencies
- Demonstrates the most granular possible piece of your platform’s functionality
- Uses the simplest code that could possibly work
- Does not contain code that does not demonstrate the functionality you’re conveying
- Is written in a language that your developers are likely to want to use
- Is subjected to the same process as the rest of your production code (including QA, source control, unit testing, versioning, etc.)
- Is intended to get developers to adopt your product or feature
See the difference?
It is possible to create both demos and code examples economically. It happens to be one of those tasks that is a prime candidate for outsourcing, even if your company is small and your platform is not necessarily mature. We are doing both demo/prototype and code example projects for a couple of clients at the moment.
With this post I’m kicking off a new category of posts for the blog, Platforms. I’ll go back and retcon some of the old posts I’ve written on this subject into this category so it’ll all be here.
Related posts:
