3 reasons to host a docathon for your open source project

A docathon is a focused, time-boxed event where a group of people get together (in person, on a video call, or in a Discord channel) and write documentation for an open source project. The model is borrowed from the hackathon tradition, except the deliverable is docs, not code. I have run three docathons in the last two years, helped advise on two more, and I am now a believer. Here are the three reasons I think every project maintainer should consider hosting one, what it takes to actually pull off, and the parts that did not work the way I expected.

The honest disclaimer first. I run a small consulting business, the projects I work on are mostly mid-sized open source tools (a few thousand GitHub stars, a handful of regular contributors), and my docathon experiences are in that range. If you maintain a project with a million users, your situation is different. Most of what I am about to say still applies, but the scale and the politics of a docathon shift when there are corporate stakeholders.

Reason 1: documentation gaps are easier to see when people are looking

Every maintainer knows there are documentation gaps. Most of us keep a private list somewhere. The problem is that we cannot see our own blind spots, and the people who hit the gaps are the ones who do not raise their hand in the issue tracker. They give up and go use a different tool, or they file a vague “the docs are confusing” issue and never come back.

A docathon fixes this in a way that nothing else I have tried does. You get a roomful of people (even a small room, five to ten people is enough) who are using the project with fresh eyes. Within an hour they will find gaps you did not know existed. The signal is not in any one gap. The signal is in the pattern. If five people in a row try to install the project and the same step is missing from the README, that is a real gap. The fact that nobody filed an issue about it is a separate problem, but at least you now know.

In our first docathon, in late 2024, the group found 47 documentation issues in a single day. We had been maintaining the project for three years. The 47th issue was a missing section in the upgrade guide that had been there since version 1.0. I had read that section of the upgrade guide a hundred times and never noticed the omission. Fresh eyes, in a focused setting, will find things you have stopped seeing.

Reason 2: a docathon is the lowest-friction way to onboard new contributors

Open source projects have a perennial onboarding problem. New contributors show up, try to file a useful issue, get stuck on the contribution guidelines, and leave. The standard advice is “make your contributing.md clearer.” That helps, but it does not solve the deeper problem, which is that contributing to a project is a skill you learn by doing it with other people.

A docathon is a much better on-ramp than a code contribution. The barrier to entry is “can you write a sentence and use a pull request.” The reward is “you have a merged contribution in less than an hour.” That is a meaningful win for someone who has never contributed to open source before, and the project gets usable documentation out of it.

What a docathon actually delivers, in our experience:

• First merged contribution in under an hour. The PR review is in the room, so the cycle from “I wrote this” to “this is in main” is the length of a coffee break.
• A real PR review by the maintainer, in real time. The new contributor gets feedback they can act on, not a six-day GitHub comment thread.
• A working knowledge of the contribution workflow. The contributor now knows how to fork, branch, commit, push, and open a PR on your project specifically. The next contribution is much faster.
• A small community of people who have worked together. The docathon creates a Slack thread, a Discord channel, or just a list of GitHub handles that the new contributors recognize. That social layer is what keeps people around.

In our second docathon we onboarded four new contributors. Three of them had never opened a pull request on any project. By the end of the day all three had merged docs contributions, and one of them came back the next month to help with a small code change. We had tried for two years to convert lurkers into contributors. The docathon did it in a day. The reason is that the cost of the first contribution is much lower when the contribution is a paragraph, not a function.

If you are a maintainer reading this and thinking “but I need code contributions, not docs,” I want to push back on that. The single most reliable predictor of whether a new contributor sticks around is whether their first contribution got merged in a reasonable time and they got a friendly review. Docathons are a forcing function for that. The next time you see a first-time contributor, the docathon is the reason they are there.

Reason 3: docs are the worst kind of work to do alone

Writing documentation is the kind of work that is genuinely hard to do well in isolation. It requires you to read your own writing as if you are a stranger, and that is not a thing humans are good at. The reviewer in your head, the one who notices “this sentence does not parse” or “I assumed the reader knows what a router is,” that reviewer is not the same person who wrote the sentence. When you write alone, the reviewer never shows up.

A docathon creates a group setting where the reviewer is built in. People read each other’s drafts in real time, ask the obvious question, and the writer revises on the spot. The flow is closer to pair programming than to solo writing. The docathon is not faster than solo writing, but the quality of the output is meaningfully higher, and the maintainer gets to see which parts of the docs trip up new readers, which is the most useful data you can collect about your documentation.

The thing I underestimated is the social cost. A docathon requires the maintainer to be in the room and responsive. You cannot run a docathon and treat it as “background work while I do my day job.” People have questions. Some of the questions are about your judgment calls in the code, and they deserve real answers. The docathon is a community event, and you are the host. I have seen docathons fail because the maintainer was in another tab the whole time.

Trade-offs

Hosting a docathon is not free in time. The honest planning cost is about 8 to 12 hours of organizer time per event, plus the day of. You need to scope the work (which sections need the most help), recruit participants (the first one is the hardest, the second one is easier because you have a track record), and run the event itself. If you maintain a project with a small user base, recruiting participants is the part that will eat your time.

The other trade-off is that documentation contributions look different from code contributions. A new contributor who lands a docs PR (pull request) is learning a different skill set than a contributor who lands a code PR. The conversion rate from “docs contributor” to “regular code contributor” is real but modest. I would put it at around 10 to 15 percent in our experience, which is better than the 2 to 3 percent baseline for cold-outreach contributions, but it is not a magic number.

The migration from “thinking about it” to “running one” took us about six weeks of prep the first time. The second time it took two weeks because the playbook was already in our heads. The third time we ran it inside a one-week sprint. The first docathon is the expensive one. After that the per-event cost drops fast.

If you maintain a project with at least 100 GitHub stars and you can find five people willing to show up for a Saturday afternoon, a docathon is a clear win. If you maintain a project that nobody uses yet, host a smaller event, maybe three people, and focus on the install instructions. The install instructions are always the most valuable doc to write, because they are the gate to everything else. If you maintain a project with a million users and a corporate governance model, the docathon still works, but the recruiting and the politics shift. Run a smaller one first to learn the shape of it.

If you only do one thing from this article, scope a docathon for the next month. Pick a Saturday. Pick a section of the docs that has been bothering you. Post a one-line call for participation in your Discord or your GitHub Discussions. The first docathon is the hardest one to start, and the second one is easy.