Developers evaluate your product by copying your code samples and seeing if they work. If the sample fails or requires too much modification, they assume your product is hard to use.
Great code samples are the shortest path from "considering your product" to "integrated and working." Here's how to create them.
Why Code Samples Matter More Than Documentation
Documentation explains what's possible. Code samples show how to do it.
Developers learn by doing, not reading. They:
- Copy your sample
- Run it
- Modify it for their needs
If step 2 fails, they leave. No second chances.
The Three Types of Code Samples
1. Quickstart ("Hello World")
Purpose: Get developer from zero to working in <5 minutes.
Characteristics:
- Minimal setup
- Runs immediately
- Demonstrates core value
- Not production-ready, but proves product works
Example: Stripe's first charge:
const stripe = require('stripe')('sk_test_...');
const charge = await stripe.charges.create({
amount: 2000,
currency: 'usd',
source: 'tok_visa',
});
Shows "you can charge a card" in 4 lines. Details come later.
2. Integration guides (Real-world patterns)
Purpose: Show how to integrate into common scenarios.
Characteristics:
- More complete than quickstart
- Handles errors, edge cases
- Follows best practices
- Still simplified vs. production
Example: Twilio's "send SMS from web app" guide:
- Express.js endpoint
- Error handling
- Environment variables
- Form validation
Shows the pattern, not just the API call.
3. Reference implementations (Production-ready)
Purpose: Complete applications developers can learn from or fork.
Characteristics:
- Full applications with authentication, database, UI
- Production patterns (error handling, logging, testing)
- Commented thoroughly
- Open source repositories
Example: Supabase examples repository - full stack apps using Supabase for auth, database, storage.
What Makes Code Samples Work
They run without modification:
Bad sample:
// Replace with your API key
const apiKey = 'YOUR_API_KEY';
Developer has to find where to get API key, create account, modify code.
Good sample:
// Get your API key from: https://dashboard.example.com/api-keys
const apiKey = process.env.API_KEY || 'pk_test_12345';
Includes test key that works immediately. Link to get real key for later.
They handle errors:
Bad sample:
response = api.create_user(email, name)
user_id = response.id
Fails silently if API returns error. Developer confused.
Good sample:
try:
response = api.create_user(email, name)
user_id = response.id
print(f"User created: {user_id}")
except APIError as e:
print(f"Error creating user: {e.message}")
Shows what success and failure look like. Developer knows if it worked.
They show the full context:
Bad sample:
const result = await embedText(text);
Where does embedText come from? What import is needed?
Good sample:
import { OpenAIEmbeddings } from '@langchain/openai';
const embeddings = new OpenAIEmbeddings({
apiKey: process.env.OPENAI_API_KEY,
});
const result = await embeddings.embedQuery("Hello world");
Complete code that can be copied and run. All imports included.
They use realistic data:
Bad sample:
{
"name": "foo",
"value": "bar"
}
What should name and value actually be?
Good sample:
{
"name": "John Smith",
"email": "john@example.com",
"purchase_amount": 49.99
}
Realistic data shows what fields mean. Developer understands structure.
Code Sample Best Practices by Language
JavaScript/Node.js:
Use modern syntax:
- async/await, not callbacks
- ES6 imports, not require (unless targeting older Node)
- const/let, not var
Include package.json: Show dependencies and versions.
Example structure:
/example-name
- README.md
- package.json
- index.js
- .env.example
Python:
Use virtual environments: Show how to set up venv in README.
Include requirements.txt:
Pin major versions: requests>=2.28.0,<3.0.0
Use type hints:
def create_user(email: str, name: str) -> User:
Shows expected types. Helps IDEs autocomplete.
Go:
Use modules: Include go.mod file.
Show error handling: Go developers expect errors checked. Don't skip this.
Example:
user, err := api.CreateUser(email, name)
if err != nil {
return fmt.Errorf("creating user: %w", err)
}
Ruby:
Use Bundler: Include Gemfile.
Show Rails patterns if relevant: Developers expect Rails conventions in Rails samples.
cURL:
Format for readability:
curl -X POST https://api.example.com/users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"name": "John Smith"
}'
Backslashes for multi-line. Easy to copy/paste.
Interactive Code Samples
Let developers run code without leaving docs:
Live editors: Embed RunKit, CodeSandbox, or Replit in documentation.
Developer clicks "Run" and sees result immediately.
Example: Algolia's InstantSearch playground - modify code, see search results update live.
API explorers: Interactive forms that generate API calls.
Example: Stripe API Reference - "Try it" button on every endpoint. Fill in parameters, see real API response.
Benefit: Developer validates that API works before writing any code.
Sample Code Organization
In documentation:
Co-locate samples with relevant docs:
Don't put all samples in one "Examples" section. Include relevant sample where concept is explained.
Example: When documenting authentication, show auth code sample right there.
Progressive disclosure:
Start simple:
const user = await api.getUser(userId);
Then show more complete version:
const user = await api.getUser(userId, {
include: ['profile', 'settings'],
cache: false
});
Repository organization:
For multi-sample repositories:
/examples
/quickstart-node
/quickstart-python
/quickstart-ruby
/integration-nextjs
/integration-django
/full-app-ecommerce
/full-app-saas
Each example in its own directory with complete code.
README in each directory:
- What this example demonstrates
- How to run it
- Key files to look at
Testing and Maintaining Code Samples
Samples must work when developers try them:
Automated testing:
Treat samples like production code. Run them in CI.
Example:
# GitHub Actions
test-samples:
- run: cd examples/quickstart-node && npm install && npm test
- run: cd examples/quickstart-python && pip install -r requirements.txt && pytest
Every PR that changes samples must pass tests.
Version pinning:
Don't:
"dependencies": {
"stripe": "*"
}
Sample breaks when major version releases.
Do:
"dependencies": {
"stripe": "^12.0.0"
}
Pin major version. Update deliberately.
Deprecation warnings:
When API changes, update samples before old API is deprecated.
Add warnings to outdated samples:
// ⚠️ This sample uses API v1 which is deprecated.
// See v2 sample here: https://...
Making Samples Discoverable
Developers should find samples when they need them:
In documentation: Link to relevant sample in every doc section.
In GitHub: Create examples repository. Promote in README.
Example: Vercel's examples repository - hundreds of starter templates, easy to discover.
In product: Link to samples from dashboard, error messages, onboarding.
Example: When Stripe integration fails, error message includes link to sample code.
In search: SEO-optimized titles and descriptions.
Example: "How to send SMS with Twilio in Node.js" ranks in Google.
Language Coverage Strategy
You can't maintain samples in every language:
Priority tier 1 (must have): Languages your customers actually use. Check analytics:
- Which SDKs are downloaded most?
- What languages appear in support tickets?
- What do customers request?
Priority tier 2 (should have): Common languages for your market.
- APIs: JavaScript, Python, Ruby, Go, PHP
- Mobile: Swift, Kotlin
- Enterprise: Java, C#
Priority tier 3 (nice to have): Less common but requested languages.
Maintain officially: Tiers 1 and 2. Samples tested and updated with each release.
Community-contributed: Tier 3. Accept contributions, but don't commit to maintenance.
The Sample Code Review Process
Before publishing a code sample:
Checklist:
- [ ] Runs without modification (with test credentials)
- [ ] Handles errors gracefully
- [ ] Uses current API version
- [ ] Follows language best practices
- [ ] Includes all imports/dependencies
- [ ] Has realistic example data
- [ ] Works with stated package versions
- [ ] README explains what it does and how to run
- [ ] Automated test passes
- [ ] Developer who didn't write it can run it
If you can't check all boxes, sample isn't ready.
When Samples Replace Long Documentation
For some products, samples are the primary documentation:
Works well for:
- Simple APIs with clear patterns
- Products where "show me" beats "tell me"
- Developer tools where code is self-explanatory
Example: Vercel's examples repository. Each framework/use case gets working sample. Minimal written docs needed.
Doesn't work for:
- Complex products with many features
- APIs with nuanced behavior
- Products requiring conceptual understanding first
Samples complement docs, not replace them. But for the right products, samples can be the main teaching tool.
Measuring Sample Effectiveness
Track:
Copy button clicks: Are developers copying your samples?
Sample repository traffic: Views, clones, forks of example repos.
Support tickets referencing samples: "I tried the sample and got error X" - means they're using samples.
Time to first API call: Developers who use samples integrate faster.
Ask in onboarding surveys: "Did you use our code samples? Were they helpful?"
Getting Started with Code Samples
Week 1: Create quickstart sample for primary language. Test it with new developer.
Week 2: Create 3 integration samples for most common use cases.
Month 2: Build automated testing for samples. Set up CI.
Month 3: Expand to top 3 languages. Create examples repository.
Ongoing: Update samples with API changes. Add samples for new features.
Great code samples are the difference between "I tried your product" and "I integrated your product."
Developers trust code they can run more than marketing copy or documentation. Give them code that works.