[Season of Docs] · August 19, 2019 · 6 min read

Understanding Open Collective's documentation

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:

1. What is the history of the documentation I am working with? On which platforms was it published?
2. How big is the documentation? How many pages are relevant to my work?
3. Which categorization method being used? Which personas (reader profiles) that documentation seeks to inform?
4. 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.

Most links to external pages will take you directly to their archived versions on the Internet Archive to preserve the historical context of this report.

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.

Mapping

From the GitHub wiki to GitBook, the documentation has gained a little over 60 additional pages and is now structured as follows:

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 Collectives, Backers & Sponsors and Fiscal Hosts have a clear purpose to help users and deserve extra attention. On the other hand, sections like Developers, Internal and 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 Translators and Community Guidelines) and pages that can be merged into a single section of the documentation (pages under Developers, Design and About related to contributions to Open Collective as an open source project; pages under About and Product).

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) core contributors, collectives, backers, sponsors, 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:

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!