Documentation? Yawwwwwn

Nobody Likes Writing It, Everyone Likes Having It

Let’s be honest: no developer wakes up excited to write documentation.

We do, however, wake up annoyed when:

  • Docs are outdated
  • Endpoints don’t match reality
  • Someone says “the README should explain this” and it very much does not

This is why documentation should be automated as aggressively as possible. Humans are bad at keeping docs in sync. Machines are excellent at it and don’t complain.

Automate or It Will Rot

Manual documentation has a natural lifecycle:

  1. Written with good intentions
  2. Slightly out of date
  3. Actively misleading
  4. Quietly ignored

The solution is simple: generate documentation from the source of truth.

If your API already has:

  • Types
  • Schemas
  • Contracts

…then your documentation should be derived directly from them.

Swagger: Let the Types Do the Talking

Tools like Swagger allow you to auto-generate API documentation directly from your type definitions.

This means:

  • Every API change updates the docs automatically
  • Endpoints, payloads, and responses stay aligned
  • There’s no copy-paste tax
  • Nobody has to remember to “update the docs later” (they won’t)

Your future self will thank you. So will every teammate who doesn’t have to reverse-engineer an endpoint at 4:57pm.

Docs Belong in the Repo

Auto-generated docs should:

  • Live in the repository
  • Be versioned with the code
  • Change when the code changes

They should not live in:

  • A forgotten CMS
  • A wiki nobody trusts
  • A magical portal “owned” by one person who’s on vacation

If docs aren’t close to the code, they drift. If they drift, they die.

Keeping docs in-repo ensures:

  • Pull requests show doc changes
  • History is preserved
  • Reality and documentation stay coupled

The Best Documentation Is the Code Itself

Here’s the quiet secret nobody likes to admit:

Well-written code is already documentation.

Clear naming, small functions, and obvious control flow explain intent better than paragraphs of prose ever will.

Code that documents itself tends to have:

  • Small, single-purpose functions
  • Descriptive names instead of clever ones
  • Minimal hidden side effects
  • Few surprises

If understanding a function requires scrolling, cross-referencing, and light meditation, no amount of external documentation will save it.

Comments and docs should explain why something exists—not compensate for unreadable code.

Treat Docs Like a Build Artifact

Documentation should feel less like prose and more like output.

Ideally:

  • Generated during CI
  • Reviewed automatically
  • Updated on every meaningful change

If docs require heroics to maintain, they won’t be maintained.

Now We Also Have to Think About MCP 😌

Modern documentation isn’t just for humans anymore.

With MCP (Model Context Protocol) entering the picture, documentation increasingly serves machines as well as people.

This raises the bar:

  • Docs need to be structured
  • Contracts need to be explicit
  • Types need to be accurate and discoverable

Auto-generated, type-driven documentation becomes even more important when:

  • AI agents consume your APIs
  • Tools reason about your system programmatically
  • “Close enough” descriptions are no longer good enough

In a world with MCP, vague docs aren’t just annoying—they’re unusable.

Documentation as a Side Effect (The Ideal State)

The best documentation strategy looks like this:

  • Write types
  • Write schemas
  • Write code
  • Docs appear automatically

No extra meetings. No guilt. No archaeology.

If documentation feels like a chore, the system is wrong.

Final Thought

Documentation shouldn’t rely on discipline, memory, or good intentions.

Automate it. Version it. Keep it close to the code. Write code worth reading.

Because while nobody enjoys writing docs, everyone enjoys not being confused.

Back to Philosophy