Guide to Planning a Community#
What if you started a project with a thought like, “I have this great idea that I want to try on this public data!”? There is nothing to worry about if you’re the only one working on it. However, if you want to develop this project - you become responsible for making people feel included in your project.
As a ‘project lead’, you want to set up a welcoming and inclusive environment and create the first set of visions and goals for your collaborators. You cannot assume that everyone you collaborate with knows what is expected of them when they start to work with others on your project. Therefore, it’s important to set the right expectations from the beginning for your community, even though you might not have planned on having one (see more details: [Sha20]).
A Checklist for Planning Collaboration in Your Project#
The checklist below will help you in making the process of establishing collaboration in your research project thoughtfully in a structured manner.
The practices listed here are derived from and limited by the experiences of the authors who participate in several successful Open Research communities and lead community-driven projects such as The Carpentries, Mozilla Open Leaders, Open Life Science and The Turing Way. While reading this chapter, please be aware that you may need to make adjustments for projects that may be very different in nature (for example, not entirely open source).
1. Choose a Communication Platform#
When leading an open project, use collaborative and open platforms such as GitHub or GitLab.
Evaluate the need for any real-time communications, such as if a text chat system like Slack or Element/Matrix will be useful or if a mailing list will be sufficient (read details Communication Channels).
Consider a separate internal communication platform for your community members and an external one for showing what you’ve done to the rest of the world.
An X account (formerly Twitter) or a simple website (such as on GitHub pages) can be useful external platforms.
Make sure that the choices of these platforms are made to ensure that there is a low barrier to join them.
2. Provide a Project Summary File:#
The first document in your project should be a project summary file, which in a GitHub repository will be a README.md file.
This will provide basic information about your project so that people can evaluate why your project will be interesting for them.
Here is a template by the GitHub user PurpleBooth.
In this file, include what your project vision and goals are, why the project is useful, what the possible milestones are in the project, how a contributor or user can get started, who can they reach out to for help, and what is currently missing in the project in terms of stakeholders, skills, or scope.
You can use emojis, GIFs, videos, or your personal narrative to make your project relatable.
See The Atom project for example.
3. Select a Code of Conduct:#
Add an Open Source Project Codes of Conduct to your project.
This document should not be used as a token, it is very important to put intentional effort into it.
When using GitHub, you can add a “CODE_OF_CONDUCT.md” file on your GitHub repository.
List the expected and unacceptable behaviors, describe the reporting and enforcement process, explicitly define the scope, and use an inclusive tone (see GitHub instructions here).
Whenever you update your code of conduct, invite comments from your members to ensure that their concerns are addressed.
This can be done on GitHub issues, or Pull Requests.
4. Provide Contribution Guidelines and Interaction Pathways:#
A thoughtful guideline helps people decide which pathway they can choose to contribute to your project, or if they want to be in your community at all.
Make sure that your community interactions and different pathways to contribute are open, inclusive, and clearly stated.
If people can’t figure out how to contribute they will drop off without helping.
Value different types of contributions - coding projects are not only about code, therefore list documentation and other management skills as well.
You can use the Persona Creation Tool or the Personas and Pathways exercise to brainstorm who could be your possible community members.
Here is a template of community guideline provided by the GitHub user PurpleBooth.
See The Turing Way’s contributing file for reference.
5. Create a Basic Management/Leadership Structure:#
A leadership structure in an open project should aim to empower others and develop agency and accountability in your community.
You can start by listing different tasks within your project and inviting your members to lead those tasks.
Provide appropriate incentives and acknowledgment for the contributions made by your community members.
Create opportunities for members to share some leadership responsibilities with you in the project.
When inviting suggestions and ideas from the community, provide the first set of plans where your community can develop from.
See this document from Open Source Guides for reference.
6. Provide Contact Details Wherever Useful:#
Clarifying responsibilities for different members will allow people to reach out to the right person with any query.
Add details of the designated contact persons for technical problems, leadership questions, or any report on the Code of Conduct.
This will be particularly useful if something needs immediate resolution.
7. Identify Failed Approaches, and Stop Them:#
Development happens in an iterative manner, therefore, revisit your plans and ideas in regular intervals and involve your members in the process.
Check if there are parallel developments or multiple approaches that should be merged or changed.
Fail fast, fail informatively - recognize what isn’t working for your project and stop it from continuing.
Document them and share why you failed and how you change your project or approaches going forward.
For Open Research communities you can maintain transparency when discussing failures and successes but refrain from singling out or blaming others.
This iterative approach comes from Agile Practices, see these short posts for reference:
8. Have Documentation and Dissemination Plans for Your Project:#
With new members joining your project, they must be able to find the information they need without asking you.
Investing in documentation plans will free you from many communication-related challenges by sharing general information regarding past decisions or the decision making process your project uses.
A good place to store the documentation is wiki or similar platforms (like GitHub) where information can be shared transparently and updated by your community members democratically.
To disseminate outputs of your project, you should use persistent identifiers that can be shared and cited, for example, digital object identifier (DOI).
Two more points are crucial for ensuring the effectiveness of a collaborative project: addressing technical issues and valuing the importance of diversity in team building.
We have explained them in the next subchapters on Addressing Technical Issues and Valuing Diversity and Differences.