21 Dec 2025 • 3 min read

I can’t really make heads or tails of this AI-generated image, but it seems to be about the linked open-source project.

Let’s be honest about something that every open source maintainer knows but rarely admits: writing documentation is a chore. We love writing code. We love solving problems. We love that dopamine hit when the tests pass. But documentation? That’s the broccoli of software development.

I’ve been publishing open source projects for over 15 years now. In that time, I’ve created dozens of packages, some with hundreds of millions of downloads. And in hindsight, what a fool I was when it came to docs. At most, I’d write a barely usable README that covers the API basics—enough to get someone started, but nowhere near comprehensive. The kind of documentation where you’re constantly switching between the README and the source code, trying to figure out what that third parameter actually does.

The Documentation Graveyard

For most of my projects, proper documentation sites simply didn’t exist. The exceptions? Projects that got big enough that the pressure became unbearable. Nodemailer, which now sees more than a million downloads per day, eventually got a proper documentation site. But that took years of user complaints and questions that could have been answered with better docs.

The problem isn’t laziness—it’s economics. For a small open source project that maybe a few hundred people use, spending days building a documentation site feels like a poor investment. The math just doesn’t work out. So we write a README, promise ourselves we’ll improve it later, and move on to the next interesting problem.

This leaves the open source ecosystem littered with useful tools wrapped in confusing or incomplete documentation. How many excellent libraries have you abandoned because you couldn’t figure out how to use them properly?

AI Changes the Equation

Here’s where things get interesting. With AI tools like Claude, we can now generate comprehensive documentation directly from source code. Not placeholder text or generic templates—actual, useful documentation that understands what your code does.

I created a custom command for Claude Code that does exactly this. You can find it in this gist. Save it to your Claude Code commands folder, navigate to any project directory, run /create-docs-site, and watch it work.

The command analyzes your source code, extracts API details, understands the relationships between components, and generates a complete Docusaurus documentation site. We’re talking:

• Getting started guides
• Full API reference
• Usage examples pulled from your tests and example files
• Proper navigation and search
• Even custom SVG graphics for branding

One-Shot Documentation

Here’s a real example: postal-mime.postalsys.com. This entire documentation site was generated in a single run from the project folder. No manual editing, no wrestling with static site generators, no staring at a blank page trying to figure out how to explain what the library does.

The AI reads your code, understands the intent, and writes documentation that a human would actually find useful. It’s not perfect—you might want to add some domain-specific context or adjust the tone—but it gets you 90% of the way there in minutes instead of days.

The Unexpected Benefit

But here’s what I didn’t anticipate: this approach works for other people’s projects too.

Ever used a library where you kind of understood the basics but never quite grasped all the options? Where the README shows the happy path but you’re trying to do something slightly different? Now you can just clone the repo, run the documentation generator, and have a full searchable documentation portal explaining everything the library can do.

You’re not dependent on the maintainer’s documentation skills or available time anymore. If you need better docs for a dependency, you can generate them yourself.

What This Means for Open Source

I think this fundamentally changes the viability calculation for small open source projects. That nifty utility you wrote for yourself and published "just in case someone else needs it"? It can now have professional-grade documentation without the professional-grade time investment.

The barrier to entry for properly documented open source just dropped by an order of magnitude. And that means more useful tools become actually usable by people who discover them.

We spent years telling developers they should write better documentation. Turns out, maybe we just needed to wait for the tools that could write it for us.