20 February 2023


Fully-executable code but single-focused for third-party developers to use as a learning exercise.

Also Known As: Demo

Problem: You want to show developers how to use your product/service, but there are enough details and/or need for precision that human language isn't sufficient to get the point across. You want developers to be able to see how to use your product/service from code.

Context: The product/service is one that is callable or usable from code, and is one that developers will use from code often. You want the code to be visible to as many developers (customers or otherwise) as possible, maximizing its reach.

Solution: Write code that illustrates a particular aspect or point or element of your product/service. Keep it as simple as possible--leaving out validation, security, edge-case handling, and so on--so as to focus primarily on the single core idea that your sample/example is looking to solve. Place that code someplace widely accesible (such as GitHub, your Guides or Reference Documentation, or your Forums) so that developers can discover the code as they learn more about your product/service.

Consequences: The sample/example needs to be small enough to illustrate a single point, only, or you run the risk of developers being overwhelmed with too many details and losing track of what's going on. For this reason, while samples/examples are executable, they typically do exactly one thing and nothing more.

Note that developers are fond of taking samples/examples and using them "as is" for their own work, changing only those elements which are necessary to get it working inside their own applications. This often means that if the sample/example contains no validation or security, then the developer will also often leave out validation or security. Make sure Legal drafts a disclaimer for all sample/example code reminding developers that this code is not production-ready.


Tags: devrel   patterns