The Documentation Problem

Documentation should keep pace with code, however, we usually write it, promptly forget about it, and six months later it's a misleading relic. At InfoEmu, we've been tackling this challenge head-on with a pattern we're calling "code-driven documentation."

Solving Docs Decay

Our approach is simple yet powerful:

Document in the code itself - Not in separate markdown files
Automate extraction - Pull examples directly from working code
Continuous integration - Update docs automatically when code changes

This ensures documentation stays accurate and removes the separate maintenance burden.

How It Works

We use special code annotations to mark exemplary patterns. Here's a simplified version:

// @BestPractice ComponentPatterns
// @BestPractice.description
// We use functional components with explicit return types
function ProductCard({ product }: ProductProps): JSX.Element {
  return (
    <div className="p-4 rounded shadow">
      <h3>{product.name}</h3>
      <p>{product.description}</p>
    </div>
  );
}
// @BestPractice.end

Our custom tool scans the codebase, extracts these patterns, and generates documentation automatically. The entire process happens during CI/CD, so docs update whenever the codebase changes.

Real-World Implementation

We've built this approach into our development workflow with three key components:

Annotation standard - Consistent way to mark best practices in code
Extraction tool - Node.js utility that pulls examples from code
CI integration - Automatic documentation updates on deploy

When a developer changes a pattern that's been documented, the docs update automatically. No more stale documentation!

The Impact

This approach has transformed how we maintain knowledge:

Higher quality examples - Real, working code instead of contrived snippets
Documentation that evolves - Examples stay current with our latest patterns
Reduced maintenance burden - No separate documentation updates required
Streamlined onboarding - New developers see actual production patterns

Try It Yourself Today

Close.com open-sourced their documentation generator. It works with JavaScript and TypeScript codebases and is simple to integrate into your projects:

npm install @closeio/best-practices-documentation

The tool provides a CLI for generating docs and APIs for custom integration. Check out the full documentation to get started.

This is a great solution for small teams or projects with a small codebase and works for free, now.

Our Future Direction

We're will be integrating this approach in our platform as a feature. We're also looking into:

Adding support more languages beyond JS/TS
Adding visual diff reviews when patterns change
Creating interactive documentation with live code examples

Code-Driven Documentation