Season of Docs 2019
Last updated
open-collective
Last updated
Google Season of Docs is a program giving technical writers an opportunity to contribute to open source projects, by paying them a three month stipend and facilitating connections between writers and projects.
As a platform that’s all about supporting the open source community, we think this is fantastic, because a lot of open source projects really need documentation help. The number one problem area Github’s Open Source Survey found was ‘incomplete and confusing documentation’.
In addition to encouraging the open source projects on our fundraising platform to participate, Open Collective itself is applying as a mentor organization. We’d love to work with technical writers who want to support our mission of open source sustainability, and can help us better communicate what our open source platform can do.
Open Collective is a platform where communities can collect and disburse money transparently, to sustain and grow their projects. Many Collectives are open source projects, and the platform is itself open source, too.
We provide tools for legal entities to fiscally sponsor Collectives under their umbrella, empowering people to create associations without the friction of setting up their own legal entity and bank account. It’s like an API between the legacy world of banks and taxes and the emerging future of distributed collaborations. For example, the Open Source Collective is a nonprofit umbrella organization for more than 1,100 open source projects.
Transparency is a big part of who we are. All Collective budgets are open, so everyone can see where the money comes from and where it goes. We run our company as an Open Collective, too, because we think transparency in technology and finances is important.
Transparency isn’t just about information being available, it has to be accessible. Documentation turns information overload into meaningful communication, and that’s why it’s so important.
This year, the organisational administrators for Open Collective in Google Season of Docs are Alanna Irving, executive director of the Open Source Collective, and Jaskirat Singh, who has participated in Google Summer of Code, a similar program, and knows the process well. Additionally, co-founder and developer Xavier Damman and CTO and lead dev François Hodierne will serve as mentors for technical documentation.
We invite all interested technical writers to read more in detail about how the program works, and see our proposed documentation project ideas below. These ideas are our wish list, but we’re also open to your ideas!
We are a fully remote company and happy to work with contributors in any location. Technical writers will be involved in our team meeting rhythms, and have regular calls with mentors.
If you have questions or want to express interest, please email info@opencollective.com and let us know!
Open Collective will be launching a new version of our API (GraphQL and REST) in mid-2019, v2, and it will need great documentation. There is also much to improve about our developer documentation overall.
Overall dev docs
Do a complete refactor/overhaul of the developer section of our docs, currently seen at https://docs.opencollective.com/help/developers.
Create an overview, FAQ and table of contents, so devs can find the info they are looking for easily.
In collaboration with our dev team, make sure all the sections are up to date and correct, and extend them to be more detailed and complete.
Add pages for any missing documentation.
Identify Collectives in our user-base who have utilized the various options and tools available to developers, and document implemented examples and demos.
Our issue bounty program for open source devs was launched in early 2019, and its documentation will need a revamp as well:
Gather feedback from participants and our dev team, and change/improve the bounty documentation accordingly.
Learn about the dev environment setup experience of bounty hunters, and improve documentation make it easier to get up and running.
API v2 docs
Work with our dev team to understand and communicate what the API can do and why our users should be excited about it. See the minimalist announcement of API v2 — we really want to take documentation and comms to a whole new level for the new version.
Fully document the new version of the GraphQL API, creating a major update to our current API docs, including Guides, Reference (GraphQL & REST), and Explorer.
Integrate the new API documentation in the developer section of our general documentation — we want all our docs in one place (https://docs.opencollective.com).
Create instructions for using a GraphQL explorer with our API, GraphQL Playground.
Create a detailed how-to (video or written) for using the new API, including example use cases and FAQ.
Facilitate the API to be self-documenting via the GraphQL explorer (as in the image below).
Project Mentors: Xavier, Francois
Open Collective’s documentation is a gitbook, located at https://docs.opencollective.com.
Currently, it gives basic information about features, how-to’s, and background info about the project. However, there is a lot of room for improvement.
Review the structure and make improvements to how the chapters and subchapters are organized to make information easier to find and understand.
Create an overview and table of contents to help people navigate to what they need.
Add images, gifs, and multimedia to enrich the content and make it more engaging.
Improve individual pages and sections to make them more clear and complete.
Collaborate with user support to identify common queries and document the solutions.
Identify key points in the software application to add links to help documentation.
Gather and document more stories of how Collectives are fundraising and using the tool.
Assess the documentation and identify key links to include in onboarding emails.
Create video tutorials:
“How to Fundraise for Open Source” — basic setup of a Collective, informed by content from the help article, Ten Steps to Successful Open Source Crowdfunding and the Quick Start Guide.
“Sponsoring open source: how and why” — setup guide to creating an organization, finding which Collectives to support (ex. Back Your Stack), bulk payments, gift cards, and some of the ‘why’ be a sponsor, based on the content in the Sponsors section of the docs.
“Take your Collective to the next level” — more advanced features like website and Github integrations, webhooks, alternative revenue streams, using the Open Collective API, bounties, and other more technical or creative methods.
Project Mentors: Alanna, Jaskirat
Thanks for your interest in our Season of Docs ideas! If you want to get involved, please email info@opencollective.com and/or join our Slack.
We are happy to consider part time contributors. We are a fully remote team and everyone works different hours, so we are flexible. Google allows writers to extend their stipend We’re open to someone working fewer hours per week for a longer period. We don’t have a set number of hours in mind, as long as the writer has capacity to attend necessary meetings, communicate with us, and deliver their work as agreed. We will select the people with the best skills, experience, and fit with our team, and work out the logistical details with them from there.
We appreciate your enthusiasm! But we have only planned mentor capacity for the timeframe of the Season of Docs program, which begins in Aug/Sept this year. We aren’t able to mentor before then, and it will be difficult to contribute effectively without support. One thing we want to work on during Season of Docs is improving our systems so wider community members can more easily contribute to docs without mentorship, but we’re not there yet.
We haven’t participated in a program exactly like this, but we bring some relevant experience.
Here’s what we wrote in our organization application to Google:
Our Season of Docs administrator, Alanna, has a lot of experience in technical writing, including creating full handbooks for multiple technical projects and communities, as well as a background in translation of scientific papers and multi-lingual technical support documentation. She authored our current documentation— but we think an even more experienced technical writer can help us take it to the next level.
We also have a partnership with Maintainer Mountaineer, an organization focused on improving documentation and communications for open source projects, and have developed a great working relationship with its founder and main technical writer.
As a remote company, we have strong processes for both synchronous and asynchronous review and feedback. Alanna has recently co-authored and edited a book with a distributed team, and will bring effective processes from that experience to this work, and she has mentored numerous startup entrepreneurs in incubator and accelerator programme and facilitated multiple structured peer-mentoring circles.
Our co-admin Jaskirat is a Google Summer of Code and Google Code In Mentor and is extremely enthusiastic about his experience there.
Our criteria for selecting writers include (this list is in no particular order and is not necessarily exhaustive):
English fluency
Overall communication ability
Technical writing experience and skills
Quality of past work
Passion for Open Collective’s mission and enthusiasm for the project
Ability to work well with a remote team
Reliability and capacity to deliver
Vision for the project’s success and credible plan to achieve it
Empathy for users of both the docs and the app
New addition of ideas and approach.
We signed up for Season of Docs specifically to welcome people with fresh eyes and complementary skills, who can give us a unique perspective. Our documentation is in an “OK” state, but we need someone with the ability and passion to make it great. Our company culture is very open and experimental. We like to encourage people to run with new ideas.
The main barrier has been lack of capacity and attention from the core team. We haven’t put enough work into creating the context and invitations needed to enable others to contribute effectively to our docs. We decided to participate in Season of Docs to give ourselves some structure and a clear timeframe for devoting the required mentorship to change this.
We’ll be giving extensive mentorship support to the Season of Docs writer(s). We hope that by investing this time and energy, our systems will be in a good state to welcome more contributions from the wider community by the end of the project. We have made progress toward welcoming more code contributions from outside, and now it’s time to do the same for documentation.
We are really good at:
transparency
experimentation
practicality
openness
personal relationships
trust
caring We need to work on:
accessibility (ability for new people to get involved)
scaling (need to grow 10x and create the systems to enable that)
polish (in many ways, the app & docs are ‘good enough’, not truly great)
fully implementing experiments (instead of running to the next thing)
We generally use Slack, and have video calls on Zoom or Hangouts Meet. We also do long-form asynchronous written collaboration on Github issues and Google docs. Most of the team is in Europe, with one in New Zealand and one in Mexico, and several part-time contributors in other places, so we adapt meetings to time zones as needed. To communicate with our users, we also use Twitter and email quite a bit.
We hope that the technical writer we work with can help advise us about how to prioritize improvements to the docs. We would be happy if they worked on any of the things mentioned in the project descriptions, plus came up with their own ideas.
What seems most important to us now:
create a table of contents or better way to navigate to the information already available
extend the docs to cover all the features, without holes or outdated info
enhance the docs with concrete examples and multimedia
make short how-to videos
link the app and the docs so users can jump to context-specific help
improve onboarding emails to give just-in-time help based on user activity
We’re constantly trying to improve docs in response to user support feedback. A lot of the info users need is actually in the docs, but they have trouble finding it and contact support. This indicates our help docs are not accessible enough.
We’re not documenting support questions extensively, because volume is small enough that we can action most feedback immediately. We do track tags associated with support tickets, to see which issues are coming up most often, and periodically review that data to guide prioritisation of both docs and software improvements.
There is also scope to create more in-depth guides for specific types of users, such as a fiscal host admin guide or a sponsor guide, with highly specific info not relevant to many users but very important to a few.