As a documentarian, my work entails way more than just technical writing: it involves a systemic — not to be confused with systematic — analysis of the documentation taking into account the whole project. So whenever I start working on an open project, I ask myself the following questions:
- What is the history of the documentation I am working with? On which platforms was it published?
- How big is the documentation? How many pages are relevant to my work?
- Which categorization method being used? Which personas (reader profiles) that documentation seeks to inform?
- What is the writing style of the documentation? Is it consistent? Is a style guide available?
In this report, we will get to know a bit more about the current state of the documentation of Open Collective, the organization that welcomed me in this round of Google Season of Docs.
Open Collective is an online funding platform for open communities. It provides tools for raising and managing financial resources while making it easy to share their finances with their backers with great transparency.
Working open is one of my core principles and the source of my frustration with some open source communities — a frustration that inspired me to write the essay Open code! = working open. For this reason, when I saw Open Collective on the list of participating organizations, I had a feeling we were destined to work together.
Historical review 📎
Before being available under their own domain on GitBook [archived] , the Open Collective documentation was made available and edited on their GitHub wiki [archived] without many customization options and no page categorization. New sections were (and continue to be) created according to the demand received in communication channels such as email, Slack and their ticket system in Zendesk.
Having access to deprecated documentation when it has already been updated or moved is rare, but when it’s there, it’s a good a source for learning. For instance, there is almost no use of media such as images, GIFs, or videos on the wiki (and when there is, they are almost certainly broken because of the migration process they went through). There are also many pages in which the content revolves around references to external pages (like this section on widgets). This makes it quite noticeable that, along with a change in platform, there has been a positive change in documentation style and culture.
From the GitHub wiki to GitBook, the documentation has gained a little over 60 additional pages and is now structured as follows:
- Community Guidelines
- The Open Collective Way
- Community Guidelines
- Core Contributors Guidelines
- Core Contributors: Communication
- Core Contributors: Expenses
- Core Contributors: Leave
- Core Contributors: Compensation
- User Profile
- Log-in System
- Creating a Collective
- Quick Start Guide
- Edit Collection
- Add or Change Members
- Add Fiscal Host
- Change Fiscal Host
- Transparent Budget
- Expense Policy
- Approving Expenses
- Updates & Comms
- Funding Options
- Data Export
- Buttons & Banners
- Zero Collective Balance
- Closing a Collective
- Backers & Sponsors
- Sponsors FAQ
- Collective to Collective donations
- Gift Cards
- Bulk Transfers
- Website Badge
- Sustainer Resources
- Expenses & Getting Paid
- Submitting Expenses
- Expense Comments
- Edit an Expense
- Tax Information
- Fiscal Hosts
- Becoming a Fiscal Host
- Create a Fiscal Host
- Fiscal Host Settings
- Host Dashboard
- Add Funds Manually
- Host Fees
- Local Tax Support
- Agreement Templates
- Open Source Collective
- Contribution Guide
- Best Practices Guidelines
- Users / Emails
- README Integration
- Postgres Database
- Post-Donation Redirect
- Custom Tweets
- Manual Reporting
- Github Permissions
- Testing with Cypress
- Collective’s location
- Team Retreats
- Brussels Summer Team Retreat
- Host Admin Manual
- Issue Labels
- DNS Troubleshooting
- Developer Guidelines
- Gift Cards
- Style Guide
- Maintainerati Berlin 2019
- Google Season of Docs 2019
- Design Workflow
- Design Contribution Guidelines
Initial analysis 📎
All sections are within the scope of my project (“Improve general help documentation”) in one way or another: culture-focused sections like
The Open Collective Way and persona-focused sections like
Backers & Sponsors and
Fiscal Hosts have a clear purpose to help users and deserve extra attention. On the other hand, sections like
Design have relevant pages and need some structural modifications even though they aren’t a priority.
Note that the categorization of sections and related pages, as well as naming scheme, is not consistent. That’s an indication that they were created following different demands with multiple layouts in mind. There are also a small number of duplicate pages (such as
Community Guidelines) and pages that can be merged into a single section of the documentation (pages under
About related to contributions to Open Collective as an open source project; pages under
The homepage doesn’t help the reader understand right away which one of the personas covered by the documentation they are. Who are (or may be)
fiscal hosts? In the current setup, you need to visit each section to understand their roles — and some of these pages are hidden under sections with names that don’t indicate their theme effectively. Would you be able to guess that the pages about
core contributors are under
The Open Collective Way when other personas have their own sections?
The writing style is mainly conversational. The documentation addresses the reader directly several times (as in the answer
"You've come to the right place!") and replicate possible questions (such as
"Can I get a receipt for my donations?"). At times, the documentation also adopts an instructional language (like on the Edit Collectives page). However, there is no style guide for the Open Collective documentation.
Having all of that in mind, how should we proceed?
Methodological Roadmap 📎
I will adopt the following script for the remaining days of the Community bonding period:
- Detailed analysis of all pages
- What is the main subject of this page?
- Who is the page addressing?
- Is its tone conversational or instructional?
- Is there any media on this page?
- If so, do they need to be updated?
- If not, should we add some?
- Identification of common themes between page groups
- Proposal of a new structure
- Submission for comments and suggestions
- Presentation of the final restructuring plan
In addition, I will share ideas and findings in the
#documentation channel on our Slack. If you are interested in following this discussion, feel free to join us!