Testable Documentation - Living Code Examples

Every code snippet in Amigos is executable, testable, and trackable. Documentation that can’t run is already outdated.

Core Philosophy

“If it’s not runnable, it’s not documentation - it’s wishful thinking.”

The Go Example Pattern, Everywhere

Go pioneered testable documentation with func Example:

func ExampleReverse() {
    fmt.Println(Reverse("hello"))
    // Output: olleh
}

Amigos takes this concept and makes it universal:

Every code snippet runs
Every example has expected output
Every documentation change triggers tests
Every import is live and verifiable

How It Works in Amigos

Traditional Documentation (Dead)

# How to create a blog
Here's how you might create a blog:
```go
blog := NewBlog("My Blog")  // This might work?
blog.AddPost(post)          // Hopefully still valid


### Amigos Documentation (Living)
```markdown
# How to create a blog
import "hub.amigos.dev/blog@v1.2.3"

Example_CreateBlog() {
    blog := blog.New("My Blog")
    post := blog.NewPost("Hello", "World")
    blog.Publish(post)
    
    fmt.Println(blog.PostCount())
    fmt.Println(post.URL())
    // Output:
    // 1
    // /posts/hello
}

Key Features

1. Executable Snippets

Every code block can be executed directly:

amigos run docs/example.md#Example_CreateBlog

2. Version Pinning

Examples pin to specific versions:

import "hub.amigos.dev/auth@v2.1.0"

3. Output Verification

Expected outputs are part of the documentation:

// Output:
// user: alice
// role: admin

4. Import Tracking

Know which examples use your service:

amigos examples hub.amigos.dev/auth
> Found 47 examples across 23 services

5. Breakage Detection

When you update a service, see which examples break:

amigos test-downstream hub.amigos.dev/auth@v3.0.0
> Testing 47 examples...
> ❌ 3 examples need updating
> ✅ 44 examples still work

Implementation Details

Example Metadata

---
example: CreateBlog
imports: 
  - hub.amigos.dev/blog@v1.2.3
  - hub.amigos.dev/auth@v2.1.0
tested: 2024-03-15T10:30:00Z
status: passing
---

Continuous Testing

Examples run on every commit
Failed examples block deployment
Outdated examples get flagged
Popular examples influence API design

The Example Contract

When you write an example:

It must compile
It must run
It must produce expected output
It must use real imports
It must represent actual usage

Benefits

For Documentation Writers

Can’t write invalid code
Examples always work
Instant feedback on changes
No more “this might work”

For Service Authors

See how people use your service
Know what changes break users
Examples become regression tests
Documentation drives API design

For Learners

Copy-paste actually works
Examples are always current
Can modify and run instantly
Learn from real patterns

Advanced Features

1. Stateful Examples

Example_UserSession() stateful {
    // Setup: create test user
    user := auth.Register("alice", "password")
    
    // Example: login flow
    session := auth.Login("alice", "password")
    profile := session.GetProfile()
    
    fmt.Println(profile.Username)
    // Output: alice
    
    // Cleanup: automatic
}

2. Example Inheritance

Example_AdminPanel() extends Example_UserSession {
    // Continues from previous state
    session.GrantAdmin()
    
    fmt.Println(session.IsAdmin())
    // Output: true
}

3. Interactive Examples

Example_Calculator() interactive {
    calc := calculator.New()
    
    // User can modify these values
    result := calc.Add(5, 3)
    
    fmt.Println(result)
    // Output: 8
}

4. Performance Examples

Example_BulkInsert() benchmark {
    db := database.New()
    
    start := time.Now()
    for i := 0; i < 1000; i++ {
        db.Insert(Record{ID: i})
    }
    
    fmt.Printf("Inserted 1000 records in %v", time.Since(start))
    // Output: Inserted 1000 records in 50ms ± 10ms
}

The Network Effect

Discovery Through Examples

Search by pattern: “auth with OAuth”
Find by output: “returns user profile”
Browse by complexity: beginner → advanced
Learn by modification: fork and experiment

Example-Driven Development

Write the example first
Make it pass
Ship the feature
Examples become the spec

Integration with Amigos

In the Import Economy

Well-documented services get more imports
Examples influence service ranking
Breaking examples affects reputation
Good examples earn rewards

In the Editor

// Type "blog.New" and see:
// 📖 15 examples available
// ⭐ Most popular: Example_SimpleBlog
// 🔄 Last updated: 2 hours ago
// ▶️ Run example inline

In the Service Page

Each service shows:

Number of working examples
Coverage of API surface
Most forked examples
Community-contributed patterns

Philosophy Extensions

“Show, Don’t Tell”

Instead of explaining what your service does, show it in action.

“Test by Teaching”

The best test suite is one that teaches others how to use your code.

“Documentation as Code”

Treat examples with the same rigor as production code.

Implementation Checklist

[ ] Example runner in VM
[ ] Markdown parser for examples
[ ] Output verification system
[ ] Version pining mechanism
[ ] Downstream testing framework
[ ] Example search engine
[ ] Interactive playground
[ ] Example analytics
[ ] Fork tracking for examples
[ ] Example-based code generation

The Ultimate Goal

Every piece of code shared in the Amigos ecosystem is runnable, testable, and useful.

No more dead documentation. No more “this should work.” No more version mismatches.

Just living, breathing examples that evolve with the platform.

Questions

How do we handle examples that need external resources?
Should examples have resource limits?
Can we auto-generate examples from tests?
How do we incentivize example contributions?
Should popular examples influence API design?

p/amigos/import-economy - How documentation quality affects imports
p/moul/golang - Go’s Example function inspiration
p/amigos/technical-vision - Overall technical architecture

The future of documentation isn’t static text - it’s living code that teaches, tests, and evolves.

testable-documentation