Reference documentation that never gets outdated

Define once. Generate everything else.

Most teams maintain configuration properties twice.

Code defines them. Docs describe them.

Then things drift apart.

The problem

Engineer adds a new configuration property:

export interface DatabaseConfig {
  isolationLevel?: IsolationLevel;
  enableSsl?: boolean; 
  retryAttempts?: number; // New property
}

Deploys it. Forgets to update the docs.

Three weeks later, a user reads the documentation. No mention of retry_attempts.

They assume the feature doesn’t exist. Or worse, they assume the default behavior and it breaks their setup.

Support ticket arrives.

This pattern repeats with every config change:

• Properties added, docs lag behind

• Properties deprecated, docs still show them

• Default values change, docs show old defaults

• Types change, examples break

The documentation becomes a source of confusion instead of clarity.

Same problem, different areas

This issue also happens with:

• API parameters

• CLI flags

• Environment variables

• Feature flags

• Error codes

Anywhere docs describe what exists in code.

Why this happens

Code and docs live in two places with different owners:

In code:

• Owned by engineers

• Changes frequently

• Gets reviewed and tested

• Always correct (code is the truth)

In docs:

• Owned by writers (or engineers)

• Updates manually

• No automated checks

• Drifts out of sync

Just two systems that don’t talk to each other.

The solution

Define once. Generate everything else.

There are two approaches:

Approach 1: Define a Schema

Write a machine-readable schema as your source of truth. For example, in YAML. From it, generate code, docs, and everything else.

properties:

  - name: isolation_level
    required: true
    type: string
    enum: [READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE]
    example: READ_UNCOMMITTED
    description: Transaction isolation level

  - name: enable_ssl
    required: false
    type: boolean
    default: true
    description: Enable SSL encryption for database connections

  - name: retry_attempts
    required: false
    type: integer
    default: 3
    description: Number of times to retry failed connections

From this schema, generate:

• Server code and validation

• Client SDKs

• API documentation

• Examples

• Interactive API explorers

The schema is your contract. Everything else derives from it.

It comes with an additional benefit: by decoupling the schema from actual code, you facilitate conversations about the contract. Teams can review and agree on the API or configuration structure before implementation.

This approach works best when open standards exist for your technology:

• OpenAPI (REST APIs)

• GraphQL schemas (APIs and resolvers)

• Protocol Buffers (gRPC services)

• JSON Schema (validation and types)

• AsyncAPI (event-driven architectures)

If no standard exists, you need to build the generators yourself, which could be a stopper if resources are limited.

Approach 2: Annotate your code

Add documentation as annotations to your code. Generate docs from it.

Example: TypeScript with JSDoc

export interface DatabaseConfig {

  /** Transaction isolation level
   * @required
   * @example ‘READ_COMMITTED’
   */
  isolationLevel?: IsolationLevel;

  /** Enable SSL encryption for database connections
   * @default true
   */
  enableSsl?: boolean;

  /** Number of times to retry failed connections
   * @default 3
   */
  retryAttempts: number;
}

From annotated code, generate the intermediate schema and the reference documentation.

To create these annotations, check if your programming language has already an standard. For example:

1. Java: JavaDoc

2. Python: Google-style docstrings or NumPy format

3. TypeScript/JavaScript: JSDoc

If no convention exists, define one. Document it. Stay consistent.

This approach is simpler than defining schemas, especially when you don’t have code generators available.

How to implement it

Step 1: Document your source of truth

Write your schema file or add annotations to your code. Include descriptions, types, defaults, constraints.

Be thorough. This is the single source. Everything generates from it.

Step 2: Choose your generator

Start by checking if existing plugins work for your docs platform.

Rendering OpenAPI in Docusaurus? There’s a plugin. Sphinx? Extension available.

Schema page generated with Docusaurus

But if you need something specific (TypeScript docs in Antora, for example), you’ll need a custom solution.

Key tip for annotations: Always generate an intermediate schema file (JSON or YAML) first. Don’t try parse code annotations directly in your docs build.

If you need a custom extension, that requires dev work. We can help with that.

Step 3: Add to CI

Automate generation so it never falls behind.

On every commit:

• Validate the source

• Regenerate documentation

• Fail the build if validation fails

On merge:

• Deploy updated documentation automatically

Our advice: Start small

You don’t need to generate everything on day one.

Start with:

1. One configuration file

2. Generate just the reference table

3. Keep the rest manual

Prove it works. Then expand.

A common objection

“But our configuration is complex. We need custom documentation.”

You can still have it. Generate the reference section (the part that can be autogenerated and reused in guides). Keep step-by-step guides manual.

The result

Engineer adds a new parameter. Commits the code.

The docs update automatically.

Three weeks later, a user reads the documentation. The parameter is there.

No support ticket this time.