Documentation Tools That Don't Suck

Documentation has a chicken-and-egg problem. Nobody reads docs because they're out of date. They're out of date because nobody maintains them. Nobody maintains them because the tools are frustrating. Break the cycle by picking better tools.

We've tried most documentation options over the years. These are the ones that stuck because they make writing and maintaining docs less painful.

The Problem With Most Doc Tools

Common issues we've hit:

• Wiki hell - Confluence-style wikis become graveyards of orphaned pages that nobody can find.
• Too much friction - If updating a doc requires a separate app, login, and complex editor, it won't happen.
• Poor search - What good are docs if you can't find anything?
• Sync nightmares - Docs that live separate from code get out of date instantly.

The best documentation tools minimize these problems. Here's what works for different use cases.

Code Documentation: In the Repo

For developer documentation, keep it with the code. Period. When docs live in a separate system, they drift. When they're in the same repo, updating them is part of the pull request.

README Files

Every project needs a README that covers:

• What this thing does (one paragraph)
• How to get it running locally
• Key commands (dev, test, build, deploy)
• Where to find more information

That's it. Keep it short. A 50-page README is just a wiki with extra steps.

Code Comments

Comment why, not what. // Loop through users is useless. // Filter inactive users first to avoid hitting rate limits is helpful.

For functions that aren't obvious, JSDoc comments work well and give you IDE tooltips as a bonus:

/** * Calculates shipping cost based on weight and destination. * Returns 0 for orders over $100 (free shipping threshold). */

Architecture Decision Records (ADRs)

Keep a /docs/adr folder with short documents explaining major technical decisions. Each one covers: context, decision, and consequences.

This saves hours of "why did we do it this way?" conversations. The answer is documented.

Documentation Sites: What We Use

Mintlify

Our current favorite for developer documentation sites. Write in Markdown, get a beautiful site. The search is excellent, and it stays in sync with your repo through Git.

The pricing is reasonable for what you get, and setup takes about 30 minutes.

Docusaurus

Open source, maintained by Meta, very flexible. It's React-based, so you can add custom components when Markdown isn't enough. More setup than Mintlify but no hosting costs.

GitBook

Good if you want the Git integration but prefer a web editor to local files. The free tier is usable. The interface is clean and search works well.

VitePress

If you're already in the Vue ecosystem, VitePress is great. Fast, simple, good looking defaults. It's what the Vue docs use.

Internal Wikis: Notion

For internal knowledge bases, we've settled on Notion. Yes, it has problems. No, there's nothing better for the price.

What makes it work:

• Easy editing - Anyone can update a page without learning Markdown
• Search that actually works - Unlike Confluence
• Templates - Consistent structure for common doc types
• Databases - Track things like tool decisions, vendor contacts, process docs

What makes it frustrating:

• Can get slow with lots of content
• Offline support is weak
• Export options are limited

Despite the limitations, it's where our internal docs live. The team actually uses it, which beats a "better" tool that nobody touches.

API Documentation

APIs need special treatment. Interactive docs that let you make real requests are infinitely better than static reference pages.

Swagger/OpenAPI

Define your API in OpenAPI format, generate documentation automatically. Tools like Swagger UI give you interactive docs where users can try requests.

The spec takes effort to maintain, but it also generates type definitions and client libraries. Worth it for any public API.

Readme.com

If you're building a developer product and want polished API docs with guides, API reference, and changelog in one place, Readme is excellent. Not cheap, but good for products where documentation is part of the value proposition.

Postman Collections

Share a Postman collection with example requests. Not as polished as dedicated doc tools, but developers can import it and start making requests immediately. Good for internal APIs.

Keep It Maintainable

The best doc tool is one you'll actually update. Some principles:

Write Less

More documentation isn't better documentation. Every page you write is a page you need to maintain. Ask whether this doc will be useful in six months. If not, maybe it's a Slack message instead.

Single Source of Truth

Don't document the same thing in multiple places. When someone updates one version, the others become lies. Link instead of duplicating.

Review During PRs

If a PR changes functionality, check if it needs doc updates. Make this part of code review. "Docs updated?" should be a checklist item.

Date Stamps

For docs that might go stale, add a "Last updated" date. At least readers know how old the information is.

Dead Link Checks

Run automated link checks on your doc sites. Broken links erode trust. Tools like lychee or markdown-link-check catch them before users do.

What We Skip

Tools we've tried and abandoned:

• Confluence - Slow, clunky, search is terrible, pages become impossible to find
• Google Docs for documentation - Works for one-off docs, falls apart for anything organized
• Custom wiki solutions - More maintenance than they're worth
• Heavyweight CMS platforms - Overkill for documentation

The Real Secret

Good documentation is a habit, not a tool choice. Even the best tools produce bad docs if nobody's committed to maintaining them.

Start by documenting what frustrates you most when it's missing. That's probably what frustrates others too. Small, useful docs beat ambitious documentation projects that never get finished.

Make it easy to write, easy to find, and easy to update. Everything else is secondary.