Documentation in open source projects

By Janus Boye

“The best documentation is written by the people who use it.”

That sentence, offered almost in passing by Milana Cap, neatly sums up a decade and a half of hands-on experience with open-source documentation.

Milana Cap is a WordPress engineer at XWP and a long-standing lead in the WordPress Documentation Team. She has spent more than a decade working inside one of the world’s largest open-source communities, first as a contributor and later as a maintainer and organiser. Few people have seen as many documentation initiatives start, stall, recover, and evolve as she has.

Documentation is often talked about as a deliverable. Something you produce, publish, and then hopefully keep up to date. In open-source projects, that way of thinking quickly breaks down.

In a recent member call, Milana Cap shared a perspective that resonated strongly with the group: documentation is not a static asset, but a supply chain, only as strong as its weakest link. The conversation drew on Milana’s long experience in the WordPress community and was enriched by active participation from across ecosystems, including contributors from the TYPO3 community, who brought complementary perspectives and challenges into the room.

Further down, you can find the full recording and Milana’s slides if you want to explore the details in more depth. The reflections surface lessons that apply well beyond open source, and let us start with a key documentation insight.

Documentation as a supply chain

Milana opened the session with what she described as the central idea behind all her work with documentation.

Milana’s core idea is simple, but powerful. Documentation connects a chain of people and roles:

  • Users, who notice errors or missing explanations

  • One-time contributors, often users who fix a small thing

  • Maintainers, who review, merge, and keep things coherent

  • Potential contributors, who might stay if onboarding makes sense

  • The project as a whole, which depends on clear roles and workflows

If any link in that chain is weak, the whole system slows down.

This framing shifts the focus away from individual pages and towards flow. Early on, Milana noted that writing documentation is usually the easy part. The hard work comes later, with onboarding new contributors, maintaining quality, and keeping momentum when teams are stretched thin. How easily can feedback move upstream? How smoothly can someone move from reader to contributor? How much friction do maintainers experience?

The bewitched cycle

Many open-source projects get stuck in what Milana calls the “bewitched cycle”. It usually starts with good intentions.

The project grows. More users arrive. More documentation is needed. So the project asks for help.

People show up and ask how they can contribute. But there is no time to onboard them properly, because everyone is busy writing documentation. And there is no onboarding documentation, because there has never been time to write it.

Some potential contributors leave immediately. Others try to figure things out on their own and submit contributions that miss the mark. Maintainers then spend time fixing or reworking those contributions, which leaves even less time for onboarding.

The project concludes it needs more people, and the cycle starts again.

The uncomfortable conclusion is that the only real way out is to stop and invest in onboarding and workflows, even when it feels like you cannot afford to.

What helps, and what hurts

Milana shared a pragmatic set of dos and don’ts that came out of years of lived experience.

What helps:

  • Making it easy to report issues and suggest improvements

  • Making it easy to edit and update documentation

  • Using version control with full contribution tracking

  • Having clear onboarding documentation

  • Documenting workflows, roles, and processes

What hurts:

  • Manually processing reports and contributions

  • Tooling that is hard to maintain

  • Tracking contributions outside the main workflow, for example in spreadsheets

  • Assuming that “everyone will do their best” because it is open source

Different parts of this system benefit different people. Easy reporting and editing primarily help users. Onboarding documentation mainly helps maintainers, by saving them from repeating the same explanations over and over. Version control and contribution tracking support maintainers and active contributors alike. Clear workflow documentation benefits the entire project.

Several people on the call noted how often the don’ts are simply the result of missing or overstretched dos.

Treat documentation as code

Drawing on lessons from WordPress, Milana argued strongly for treating documentation as code.

Using a system like GitHub as the source of truth gives you versioning, history, and contribution tracking by default. It also lowers the barrier for contributors who already understand pull requests and reviews.

Where WordPress has struggled, in Milana’s view, is being constrained to specific hosting and publishing approaches. Versioned documentation, translations, screenshots, and media quickly become hard to manage when the tooling is not designed for that complexity.

The key insight here is that the best tool for writing documentation is not necessarily the best tool for hosting it. Automation between the two matters more than finding a single perfect platform.

Language, quality, and letting go

Several questions during the call focused on language quality, especially in communities where many contributors are not native English speakers.

Milana’s response was refreshingly grounded. Use a simple, clear style guide. Short sentences. No slang. Aim for a friendly, semi-formal tone. And then publish.

Waiting for perfect language, perfect tooling, or perfect linting systems can delay documentation indefinitely. In open source, something that exists and can be corrected is usually better than something that never ships.

Diversity also matters. The best way to find unclear documentation is to put it in front of people who have never seen the project before and watch where they get stuck.

Throughout the conversation, this idea kept resurfacing in different forms. Users notice gaps because they fall into them. One-time contributors fix the thing that tripped them up. Maintainers benefit when those experiences are fed back into the system.

Seen this way, turning users into contributors is not a nice-to-have. It is how quality improves, how onboarding gets sharper, and how the documentation supply chain keeps moving.

That perspective also explains why documentation work so often feels invisible until it breaks. It is infrastructure for the community, not just content for readers.

And that is a useful reminder, whether you are working on a volunteer-driven project or a large enterprise platform.

The conversation continues

The conversation on open source and documentation continues.

If reading and being part of an online call is not enough, you’re very welcome to join us more actively. Our community is built around learning together, comparing notes, and exploring how theory meets practice across roles, industries, and regions.

You can:

You can also lean back and enjoy the recording or browse the slides (as PDF)

However you choose to engage, we’re glad you’re here and part of the journey.