There are a number of things you can do to ensure that people are able to find your project, understand what it’s about, and learn how they can best contribute to it.
Deciding to Pursue the Project
Before actually pursuing a particular project, it is often a good idea to do some investigation of the idea to identify answers to the following questions:
- Impact. Does the solution we are thinking of actually positively impact the problem at hand in a measurable way? In what way would we be measuring that impact? Try using the Impact Cascade to better understand this piece.
- Liabilities. What are the liabilities we open ourselves to by pursuing this solution? Are there ethical concerns associated with doing the project? What unintended harm might be caused as an outcome of this project?
- Feasibility. Is the solution we are thinking of feasible in the available time frame and under the current financial and staffing resources we have? If not, is there reason to believe we can change those resource levels quickly enough to make a difference in our ability to deliver the project within the needed time?
- Expertise. Do we have partner subject matter experts who can help us ensure that we are driving toward impacting the problem at hand? What time commitment can those individuals give to the project?
- Partnerships. If the project is being completed to assist an organization (local or state government, non-profit/NGO, etc.), do we have good communication and necessary agreements with partner organizations for whom this project is being done?
- Users/Beneficiaries. Do we have access to potential users/beneficiaries of this project for user research and user testing? If not, how can we gain access to those communities?
- Champion. Do we have an individual who is willing to take the lead on this project and own its deliverables and its success?
In order to dive into these questions and see connections between them, you may consider filling out OpenAustin’s Civic Tech Canvas, or one of the CfA Brigade Network Project Canvases (Technology Projects, User Research Projects, Discovery Projects) for your project.
This preparatory work also provides clarity for your project team on the rationale behind pursuing the project, which they will need when writing the project description.
A brief note on timing: The answers to these questions may be different depending on the time at which you’re asking them. For example, under normal day to day circumstances, potential liabilities may not be severe or might be manageable; in a crisis situation, new potential liabilities, even with a cost of human lives, may be added, and rapidly changing situations may prevent management of those liabilities. During severe conditions, always defer to emergency management authorities (local, state and national), and have a bias toward simplicity and the creative use of existing resources over building new things.
Write and Refine Your Project Description
A good project description tells the story of the project in brief and has several key elements:
- Start with the problem you’re solving. Why does the project exist? How will your project help solve that problem? What is the rationale for pursuing this project?
- Explain in a few sentences what the project is and how it is intended to be used. Give an idea of how to get started as a user of the project.
- Give a very brief description of all the components (not just technology) of your project, including outreach, user research and design efforts, partnerships, project-related events, and big-picture technology components.
- Briefly thank prior contributors to the project.
- Provide links to places where more information can be found.
Your project description should go in your project’s README file in the Github repository, as well as in your projects list, wherever you keep that.
Make Your Project Indexable
Here are some easy things you can do to make your project more discoverable:
- Add your brigade and projects list to the
organizations.jsonfile so that it shows up on the Brigade Project Index. (Instructions are here.) - Add a description and URL in the title area at the top of the page on each of your repositories on Github.
- Add metadata files to your repository – for example, publiccode.yml or civic.json
- Add tags to your Github repository. (You can find tags that map to topics on the Brigade Project Index here.)
- Choose a commonly used open-source or Creative Commons license for your project material and software. This ensures that your project will be found by someone who searches for “open source” projects.
- Add links to Code for America and to your brigade’s website in the project’s README file.
- List the project on your brigade website. Be sure to include the “Why” first there as well.
Create a CONTRIBUTING document
A CONTRIBUTING document is a starting point for many who would like to get involved in your project. A good one does the following things:
- Starts with the problem and proposed solution, in just a couple of sentences.
- Identifies the major workstreams involved in bringing the project to life.
- Identifies the types of skills you need on the project, and what work streams they could contribute to. The idea here is to help a new volunteer easily see themselves successfully contributing to the project.
- Provides points of contact for getting involved: links to project documentation, Slack or chat channels, code repositories, relevant websites or forms, etc.
- Provides several sections of detailed information on how to contribute (as relevant to the project):
- technical details about software development processes, tools and libraries used, getting setup to work on the project, expectations for automated testing, code style, and pull requests
- human processes for data entry or conducting events related to the project
- any relevant approval steps or processes
- any relevant background, legal frameworks, or standards that must be met as a condition on success of the project
- how meetings are conducted, and a schedule of regularly recurring meetings
- contact information for a lead for each of the workstreams identified
- Provides links to background resources, talks or presentations, articles and other materials about your project and its context.
- Identifies contributors to your project. Consider using all-contributors on your project Github repository.
Additional Project Documentation Guides
If you need more information beyond this, the good news is there’s plenty of good information available online (in addition to the really helpful folks in the network)! Here are a few that have been helpful:
- Github’s Guide on Building a Strong Community, including a good section on Setting Up Your Project for Healthy Contributions
- Mozilla Science Lab’s Wrangling Web Contributions: How to Build a CONTRIBUTING.md
- FreeCodeCamp’s How to Attract New Contributors to Your Open Source Project
- The Documentation Compendium
- How to Build a Contributor-Friendly Project, by Kevin Owocki via Gitcoin
- A Template for Creating Open Source Contributor Guidelines by Safia Abdalla on OpenSource.com