How an Open Source Docathon Improved Our Documentation

We spent a weekend rewriting our docs in a public Google Doc and learned more about our product than we did in a quarter of internal planning meetings. The event was accidental. The lessons were not.

How it started

Our documentation had drifted. New features shipped faster than we could write about them, and old features still had guides written before the UI changed. We knew this. We had a roadmap. The roadmap had been on the roadmap for two quarters.

The break came from a contributor who was trying to integrate our product and got stuck. They opened an issue, then a discussion, then a thread that turned into a proposal: “What if we all get on a call for a few hours and just rewrite the worst pages together?” I said yes before I thought about it, mostly because I was tired of apologizing for the docs.

The first docathon (an event where contributors gather to write or improve documentation) was four people, six hours, and three pages of Google Doc. The second was twelve people, two days, and a complete overhaul of the quickstart guide. By the third, we had a regular rhythm.

What a docathon actually is

A docathon is to documentation what a hackathon is to code. You pick a window of time, get people in a room (or a video call), and produce something. The shape varies. Some run for an afternoon. Some run for a week. Some are focused on a single product area. Some are catch-all.

The format we settled on is a 48-hour window with a public working document. Anyone can join. There is a short kickoff where we list the docs that need the most help, people self-select what they want to work on, and we keep a shared channel open for questions. At the end, we review the diffs and merge.

It is not a sprint. It is a focused burst of attention on a thing that is hard to make time for in the regular cadence. Normal development rewards shipping features. It does not reward writing about the features you shipped six months ago.

Why the format worked

The reason a docathon is more productive than asking people to “just write a doc” in the normal course of work is the same reason a hackathon works. There is a start, an end, and a small amount of social pressure. The window is bounded, the goal is visible, and the people who show up want to be there.

The other thing that worked was the public working document. We tried Notion, we tried HackMD, we tried writing directly in the repo. The Google Doc won because it has zero learning curve, supports comments inline, and lets a non-technical person co-edit a paragraph with an engineer. Most of our best rewrites were a developer and a technical writer in the same doc, fixing each other’s sentences.

Public also meant visible. Other people could lurk and learn what was changing, which meant the announcement the next week did not feel like news. They had been reading along.

What we got out of it

Rewriting the quickstart guide was the most concrete output. The old version was 1,200 words and assumed the reader had set up their own database, configured their own secrets, and understood the directory structure. The new version is 600 words, has three screenshots, and gets a working app in the browser in under ten minutes.

Completion rate on the new guide tripled. We did not change the product. We changed the document. That ratio, three times the success rate for half the words, is the entire argument for investing in documentation.

A long list of small, fixable issues came out of the event. “The deploy button does not exist on this version.” “This screenshot is from 2022.” “The sample command references a flag that was renamed.” None of these were big enough to file an issue for. All of them added friction. The docathon surfaced them because someone was looking at every page in detail.

Most surprising of all was what the other contributors knew. They had run into edge cases. They had workarounds. They had opinions on the API. We learned more from two days of docs work than we did from a month of internal discussions, because the people who show up to write docs are the people who actually use the product.

What was hard

The first docathon was rough. We did not have a clear process. People worked on the same page. We had merge conflicts in a Google Doc, which is its own kind of hell. Two of the three pages we “rewrote” were actually worse than the originals because we tried to do too much in too little time.

By the third event we had learned a few things:

• Assign a single owner per page. Multiple people can review, but one person drives.
• Set a hard cap on scope. If the page is not done by the end of the window, ship what you have and iterate later.
• Have a reviewer whose only job is to read for clarity, not accuracy. A subject-matter expert and a clarity reviewer are different roles.
• Do not require people to know the codebase. Some of the best edits came from people who did not write the product, because they were the ones who needed the doc to make sense.

The other hard part was the post-event cleanup. A docathon produces a lot of partial work. We had to commit to a follow-up week where we merged, edited, and published. If you skip that step, the docathon was a waste. The window produces momentum, but the publishing step is what makes it real.

Trade-offs

A docathon is not free. Pulling four to twelve people off their normal work for a day or two has an opportunity cost (the value of what they would have done instead). For a small team, that cost is real. We have run the events roughly quarterly, which is the cadence we can afford.

There is also a quality risk. A page rewritten under time pressure, by a contributor who may not be a strong writer, can be worse than the page you had. The fix is the reviewer role and the follow-up week. Without those, you ship a worse doc and call it progress.

The third trade-off is the social cost. Not everyone on the team wants to write. The docathon is voluntary in our case, which means the same five or six people show up every time. That is fine, but it does mean the burden is concentrated. The fix is to rotate the reviewer role, which spreads the cost.

When a docathon makes sense

A docathon is the right tool when you have a documentation backlog and a small group of people who are motivated to work on it. It is the wrong tool if the problem is that nobody cares, or if the docs are fundamentally broken in ways that need product changes.

We use it for ongoing maintenance, not for major rewrites. A from-scratch docs redesign is a project with a real budget. A docathon is the maintenance layer.

It also works well for new contributors. Someone who is unfamiliar with the codebase can be useful in a docathon faster than they can be useful in a code review. Writing “this is what I expected to happen” and “this is what actually happened” is a real contribution, and a docathon is the lowest-friction way to make it.

What we kept

After running this for about a year, the format is stable. We do it quarterly. We announce it a week ahead. We run it for two days. We publish a recap. The recaps are short: what we wrote, what we did not finish, and what we are doing next.

The thing that surprised me most is how much the format taught us about our own product. Reading every page of your own documentation in a focused window is a forcing function for honesty. You cannot gloss over the awkward parts when you are rewriting the awkward parts in real time. That pressure, the polite pressure of a shared doc and an open channel, is what made the format worth keeping.