Making Your Project Contributor-Friendly

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.json file 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
  • 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:

4 Likes

Thanks @ryan.b.harvey this is awesome info! Here is some of our startup documentation:https://docs.google.com/document/d/1HeXBbIQHAxwwOQSZGbVl1dnkQy-Aw1bJFBXxAaq8Km4/edit?usp=drivesdk

We’re trying a new made-in-house open source Platform called digitalpublicworks.com

1 Like

Thanks for sharing your startup documentation! I hope you’ll join us for a project documentation 1:1 this weekend.

Regarding the platform, it seems like this is a really new project (I’m only seeing one project in there, and it’s the project to build the platform itself), and the Brigade Project Index effort has been going on for well over a year. I’m curious, what’s the rationale for building a separate system instead of just working on improving the index?

In any case, you should definitely ensure that Code for Milwaukee’s projects are being represented well on the Brigade Project Index, which is intended to be the primary catalog of brigade projects across the network. Happy to help with that – just reach out!

1 Like

Hey Ryan,

The current organization is new, but this less technical means of starting a project is what we’ve developed iteratively over half a year of work.

I also don’t think that these two processes are too similar or ought to be mutually exclusive.

Our process is meant to be more friendly to the non-coder and is more lightweight than the index seems to be and while I may be enthusiastic to add our projects to the index, are participants are both slow to adopt and generally reticent to do suggested things like all the steps you mentioned above.

2 Likes

Also the other projects on DPW ( I realize you’re taking about that and not the guide now), just aren’t public yet. They will be. If you make an account you can see the other projects like https://digitalpublicworks.com/projects/49268a4d-1067-4a84-8f97-c15a2ff91dc7

2 Likes

Id like to add the index instructions you provided in our project startup guide, and will do so shortly

1 Like

That’s great! Please do add whatever is helpful!

Yeah, the question wasn’t a criticism, more curiosity about the rationale. Different project for a different purpose is fine, but we’d like to try to incorporate common needs into a brigade-wide tool if possible. Less things to maintain.

1 Like

We put together a project template to launch any project quickly. We’ve included these standards as closely as we feel we can for a template. Feel free to use this template on Github, fork it, use it, contribute to it, whatever! Feedback welcomed and encouraged!

1 Like