How did Open Collective's docs change in three months?
This is my last week as a Google Season of Docs technical writer and let me tell you, working with Open Collective was a delightful experience! In the last three months, I got to know more about one of the most fascinating communities in open source, worked with dedicated contributors, and — most importantly — I had the chance to improve all of Open Collective’s help pages as much as I could.
What’s new?
🆕 Open Collective’s docs now make use of the Group functionality. Our help documentation is now 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 has 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.
🆕 Our repository’s main branch is now v2; master has been 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.
🛠️ Our GitBook now has 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 is already live! 🎉 Wondering how did it look like before and how much has it changed? The old version of our documentation can still be accessed on this page.
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 (including this one):
- Understading Open Collective’s documentation
- My first impressions of GitBook
- Is GitBook the right tool for your organization?
🙌 Closed 10 issues old and new:
- #32: A new structure for the Welcome page
- #37: Link rotting and GitBook organization of pages
- #38: FAQ: Financial Contributors
- #40: Updating references to external content
- #41: GitBook’s own version control: yay or nay?
- #44: Broken images links
- #2333: Troubleshooting guide for Github authentication flow
- #2389: Creating a style guide for Open Collective’s docs
🗨️ 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).
What’s left to do?
- 🤝 Integrate better Open Collective’s aplication interface and our documentation
- 📹 Create more multimedia content about Open Collective
- 📧 Configure a changelog system (read more about it on issue #1674: Setup Changelog / Release Notes)
- 🏠 Find a new home for Open Collective’s documentation
- 🛠️ Improve our Contributing section
- 👐 Mentor new technical writers!
This community has welcomed me with open arms and I couldn’t be more grateful for that. Open Collective has found in me a contributor for life, and I hope to keep contributing for as long as I can. Thank you Google Season of Docs organizers, Open Collective and, in special, Alanna and Jaskirat.