This post originally appeared on the Birdaro blog. Birdaro, which is powered by CSCCE, offers leadership development for open source projects. In 2025, we ran a pilot cohort of the Birdaro training program that focused on governance and documentation in open source. This post is one of several reflecting on the outcomes of the pilot cohort.
Addressing documentation debt through playbook creation
From September-December 2025, we worked with 24 scientific open source projects through the pilot cohort of the Birdaro training program. This multi-week training module, funded by the Chan Zuckerberg Initiative, focused on governance and documentation in open source (OS), and included training sessions facilitated by CSCCE staff and discussion forums for participants to learn from each other.
The choice to focus on governance and documentation for this pilot cohort was informed by our understanding of participant needs (60% of applicants identified creating contributor guides and team playbooks as a priority training area), as well as a broader appreciation of the challenges facing the scientific open-source ecosystem.
While all scientific open source projects request funding for technical work, mature projects also aim to improve their documentation and community building efforts.
– Hertweck, K., Strasser, C., & Taraborelli, D. (2024). Insights and Impact From Five Cycles of Essential Open Source Software for Science doi: 10.5281/zenodo.11201216
With this in mind, we adapted our existing Creating Community Playbooks (PBK) training course for Birdaro, and for the last six weeks of the training program we guided representatives from each of the participating projects through the process of creating a playbook in an effort to help them reduce their “documentation debt” and better support their contributors, users, and other vital stakeholders.
This is the first of two posts focusing on community playbooks as a tool for OS projects looking to address their documentation debt. We’ll start by sharing more about our approach to creating community playbooks, the different forms they can take, and the different ways the Birdaro participants applied CSCCE’s framework to their own use cases. Then, in a follow on post, we’ll highlight some of the publicly available playbooks they created and why they’re having an impact.
If you’re interested in talking to us about the future of Birdaro, please send an email to info@birdaro.org.
What is a playbook?
A playbook is a physical or digital artefact that supports members of a defined group (e.g., team members, contributors, users, or champions) in participating in the group’s activities more easily and independently. A playbook lowers barriers to participation by providing the scaffolding that makes processes, policies, and other key information accessible from a more centralized starting point. In STEM communities, we’ve been involved in creating a range of different types of playbooks:
- Team / project-specific playbooks that codify the norms and practices of a team working on a specific project and/or within the same organization. This can include policies, procedures, directories and other key information to smooth the delivery of a collaborative piece of work, or to aid a team in setting more general norms for all of their work together.
- Onboarding playbooks or welcome guides that offer new members of a team or community a roadmap for getting started. This could include information about regular activities, the tools in use, where to find archival materials, and who to contact about different topics.
- Technical playbooks or quick start guides that orient community members to a platform or tools. These are typically most useful when a tool or platform is significantly complex and previous decisions and existing workflows and templates need to be captured in a way that supports ongoing use of the tool(s).
- Champions playbooks that support more established members of a community taking on leadership roles, accessing training programs, or serving as guest speakers, mentors, or advocates
Conceptually, playbooks are a type of “higher-order” documentation. They often curate links to additional documentation, or create a logical path through a complex file hierarchy and so serve as a backbone or a map.
As we were preparing to host the pilot cohort of the Birdaro training program, we knew that some OS projects were already creating playbooks, they just used different names for them: contributor guides, user handbooks, and core team playbooks.
You can find out more about the pilot cohort of the Birdaro training program on the Birdaro website.
What does CSCCE’s Creating Community Playbooks (PBK) course cover?
PBK is a workshop-style course that spans two live sessions per week. It includes short lectures and guided activities that explore the different contexts in which structured pieces of documentation are useful, and the different strategies for creating and maintaining them. This approach is paired with facilitated “Co-Labs” in which participants work on creating or refining their own playbooks (whatever they might be called!). The course is underpinned by a CSCCE playbook framework that is designed to help participants make visible the who, what, why, when, where, and how of their community or project.
You can find more information about PBK on this page of the CSCCE website.
Why make a playbook? The challenges of documentation debt in open source projects
Documentation debt is a common and persistent problem in OS projects, with enthusiasm for creating and optimizing new features often taking precedence over pausing and ensuring documentation is organized and up to date. And since most contributors to projects are volunteers, it can be particularly challenging to encourage documentation contributions.
This leads to common and challenging outcomes for project leads:
- Volunteer contributors cannot “serve themselves” by finding policies and practices outlined somewhere. This creates human bottlenecks because the project’s core team cannot individually answer every question or personally onboard every new contributor.
- Staff or volunteer turnover leads to knowledge loss. If only one or a few contributors know how to support a feature, and they then leave the project, the people left scramble to figure things out. The impacts of knowledge loss on a project range from inefficiency to complete catastrophe.
- A project cannot easily scale. When creating new working groups or expanding projects into different countries, a lack of documentation can lead to confusion, sub-standard outputs, software vulnerabilities, and/or challenges around community engagement.
Playbooks, whatever they’re called and whatever form they take, are a natural solution for project leads, since they can act as instruction manuals for new contributors, archives of project processes and norms, and a central hub that everyone involved can maintain and develop over time.
What kinds of playbooks did the Birdaro pilot cohort make?
The pilot cohort of the Birdaro training program brought together 24 scientific OS projects, deliberately selected to span a range of contexts, sizes, and lifecycle stages. Some projects arrived with copious items of documentation that needed organizing into audience-specific streams. Others were relatively new projects who had yet to really consider how they were onboarding new contributors or articulating the governance for the project.
At the end of the PBK course, all participants share a short presentation that highlights who their playbook is for, where it will be made available, and how they anticipate maintaining the playbook over time.
Of the 24 projects that participated, more than half chose to focus on creating or updating a contributor guide. These varied somewhat in their overarching goals, with some teams choosing to create a single hub for all contributors and others designing more “choose your own adventure” style playbooks for different contributor types. Choosing to create a playbook that mapped these “contributor journeys” meant that project teams had to pause and get really clear on who their contributors were and what was blocking them from doing more for the project.
Several teams chose to focus on new contributors, creating onboarding guides to specifically help people become a project contributor.
One team chose to focus on making a champions playbook that would be useful for community members interested in setting up a new working group.
There were also several teams who focused on the end-users of their OS tool, and created user guides to describe setting up and using a platform, rather than contributing to the underlying code. And one team even decided to implement two different playbooks – one for their contributors and one for project leadership, which they are currently calling a “decision-maker playbook” (see part 2 of this post for more on that!).
How do playbooks make a difference in OS?
At the end of the training, we asked participants to reflect on what they learned and how they’ll use their playbook. Most participants indicated that their priority was sharing playbook information with their contributors, maintainers, and internal staff team. They also noted that they hoped their playbooks would help encourage new contributors and more contributions, as well as promote alignment around the core purpose of their projects.
“I really valued getting to see others’ progress on their playbooks throughout the course. Regardless of how their project status related to mine, it was helpful context to see how people thought about building and sharing their playbook.” – Birdaro pilot cohort participants
Coming up in part 2…
Since the pilot cohort of the Birdaro training program concluded at the end of December 2025, several of the project teams who participated have completed and/or shared about their playbooks more publicly. In part 2 of this blog post, we’re highlighting those projects as examples of the different ways playbooks can make a difference in OS projects!
You can find more information about everyone’s playbook (and additional program outputs) on the Birdaro website. Please send any inquiries about Birdaro to info@birdaro.org.