Google Season of Docs: Revamping Open Collective's Documentation

I had the pleasure to be one of the 42 technical writers selected to participate in the very Google Season of Docs cohort back in 2019. Under Alanna Irving's and Jaskirat Singh's mentorship, I completely revamped Open Collective's documentation. April 6, 2026

First impressions

It was a common occurrence to come across documentation pages containing instructions without supporting media (videos, GIFs, images) while other sections under the same chapter have more complete entries - for instance, Edit Collective is composed of instructions only while Add Fiscal Host incorporates supporting media.

In the pages I’ve browsed, no media is described using the alt text attribute. The lack of image descriptions hinders a complete understanding of documentation for those who use screen readers and people on slower internet connections where any media may fail to load.

Some sections of the documentation merge FAQs and direct instructions for navigating the user interface, such as Change Fiscal Host. Since there is no table of contents in the documentation interface, a user who is aware of the consequences of a change in registration records and just wants objective instructions may perceive the documentation as verbose and too tangential.

Although the language of the technical documentation is quite consistent, the publicly available Style Guide documents too little about how documentation should be written. Since the Contributing page mentions contributions to technical documentation, both Open Collective and potential contributors would benefit from more comprehensive guidelines.

Proposal and methodology

I proposed a review of users help pages, rethinking their presentation and current structure. I worked alongside the community promoting cycles of continuous feedback of varying duration. I interviewed active members from prominent and starting projects, asking them question about the current state of documentation. It took note of all internal systems used to track queries and issues and the process to document them in the Open Collective docs. I evaluated latent problems in the current version of the documentation and preparation of a plan to solve them. Lastly, I worked on Open Collective’s documentation with cycles of incremental updates and feedback.

What changed?

🆕 Open Collective’s docs made use of the Group functionality. Their help documentation was separated into nine sections: About, Product, Collectives, Financial Contributors, Expenses & Getting Paid, Fiscal Hosts, Contributing and Internal.

🆕 The Contributing section was added to help new and old contributors to understand better how to make contributions to Open Collective. It gathers contribution guidelines for Design, Development, Documentation and Translation.

🆕 Documentation now had contribution guidelines of its own, including a page of resources for documentarians, a style guide and a guide to teach contributors how to suggest changes.

🆕 Their repository’s main branch became v2; master was declared deprecated.

🆕 All key sections start with a page dedicated to frequently asked questions.

🛠️ Pages from all sections were updated to portray Open Collective’s most current interface. New media, such as GIFs, was added to demonstrate more complex actions.

🛠️ Outdated terminology such as backers and sponsors was replaced with current terminology. Names of key members of the Open Collective ecosystem (i.e. Financial Contributors, Organizations, Collectives) are now always capitalized.

🛠️ Their GitBook gained a content configuration file that tells the platform how to read our file tree and how to deal with redirects. This helps us avoid link rot, maintaining the integrity of our documentation.

The new version of Open Collective’s documentation was released on November 2019 under docs.opencollective.com/help.

Old version

The old homepage of Open Collective's documentation shows a lot of text and doesn't direct the reader to action right away. Pages are hidden under categories they may not understand.

The old page with instructions to create a collective. It only included very short context with no detailed instructions.

New version

The new homepage of Open Collective's documentation shows their mission statement and a video explainer. Pages are now grouped by purpose or personas.

The new Creating a Collective page with more detailed instructions and screenshots!

As a documentarian, my work isn’t limited to writing about how a certain product or process works — in fact, I would say that actual technical writing is only 10% of all the things I do.

My main goal is to understand the context in which those products and/or processes exist: the tools all members of the community use, the model of development, operations and delivery they chose to follow, how core and external contributors communicate with each other, how each new functionality is crafted, how every key member of their community interacts with both the platform and people around them. That’s why I invested a lot of time in understanding Open Collective as a whole. I connected with all teams and even had the chance to witness the release of new functionalities.

Our project in numbers

📝 Authored more than 120 commits on our documentation repository (and counting)

📨 Submitted 3 pull requests (#35, #36 and #39).

🤝 Attended 25 meetings

📋 Wrote 4 reports:

🙌 Closed 10 issues old and new:

🗨️ Left 4 unaddressed issues under the documentation label, including:

#2595: A new home for Open Collective’s documentation (please share your ideas and suggestions with us!)

That’s also the reason why the majority of my reports are about GitBook, our current documentation platform. I was able to work on our documentation both as an external contributor (through our GitHub mirror, submitting pull requests) and a core contributor (using GitBook’s web interface). I had to make some aggressive changes to our documentation’s structure, and those experiences helped me evaluate GitBook’s strengths and weakness and judge whether that’s still a good choice for our docs or not (my verdict: it isn’t).

Looking back

This project was concluded almost a decade ago; I departed from Open Collective in early 2021. As of 2026, their documentation adopts mixed approach: action-oriented (categorizing actions by starter actions and advanced actions) and persona-oriented (with specific sections for collectives and fiscal hosts). They continue to adopt GitBook, which has gone back to an open code release model, but I remain skeptical about it.

GitBook did solve the issue of using alternative text as a caption rather than an accessibility future. However, in recent years, I’ve heard of several organizations hit with unexpected pricing changes. They offer free community plans, but such offers always come with the caveat of maybe being revoked in the future — that isn’t unheard of in the open source ecosystem. Additionally, for projects with a strong sovereignty philosophy (e.g. Brasil Participativo), handing over complete control of their documentation infrastructure to a foreign entity isn’t a good or desirable decision. I continue to prefer solutions organizations can choose whether to host it themselves or host it with a third party.