Writing usage examples that teach through code
minimal working examples, progressive disclosure, code comments in docs, real-world scenarios, output documentation, anti-pattern examples
Usage Examples That Teach
Usage examples are the most-read part of any documentation. Most developers skip prose and jump straight to code. Your examples must work on copy-paste, use realistic data, and show output.
The Minimal Working Example
Start with the simplest possible use case that demonstrates the core value:
const cache = require('fastcache');
// Initialize with default config
const c = new cache.Client();
// Set a value with 60-second TTL
await c.set('user:123', { name: 'Alice' }, { ttl: 60 });
// Retrieve it
const user = await c.get('user:123');
console.log(user); // { name: 'Alice' }Show Real Output
Every code example should show what the developer will see after running it. Undocumented output forces readers to run the code just to see if it worked correctly.
Progressive Disclosure
Order examples from simple to complex. Start with the happy path. Then add configuration options. Then cover edge cases. Never lead with the most powerful but complex feature — you'll lose beginners before they see the value.
Comment What's Non-Obvious
Comment on the why, not the what. // Retrieve it adds nothing. // Returns null if key expired or never set is useful. Code tells you what — comments tell you why and what to expect.