Photo CCO 1.0 Dustin Lee

• Project Documentation
• Assignment: Set-Up Your Project
• Attribution

This chapter will take you through practical steps for setting up your project for participation.

Project Documentation

Documentation is one of the most important, yet least prioritized, jobs in an open project. It’s also one of the most critical for contributor success. If your environment builds are up to date - people will be successful sooner. If they are out of date, people may leave your project before ever opening an issue or contributing. Project documentation should (minimally) consider:

• Project description & goals
• How to setup technical environments
• Links to repositories, task lists & communication channels

README.md

The README file (whose name by convention is written in all-caps, and represents a request to one and all— “read me!”) is one of the first things that potential contributors will encounter when learning about your project. The aim of the README is to welcome, orient, and encourage newcomers to participate. This file will live on the web, as part of a collection of working documents on your project, called a “repository” (If your project isn’t online, don’t worry about that just yet, you’ll set that up in Module 5).

When you open your project, you may have an audience in mind (for example, software developers, educators, scientists or activists)… but you may want to reach a much broader community! Many people outside of your target audience may be interested in your project. People from all walks of life and professions– writers, designers, artists, journalists, parents, citizen scientists– may have valuable contributions to offer. Clearly communicating information about your project will enable others to understand and participate.

Here’s a sample README file from the STEMM Role Models Project. This project and all related files are hosted on the collaboration platform GitHub (more about that in Sections 4 and 5), so you’ll need to scroll down below the list of files to see the README text.

CONTRIBUTING.md

A CONTRIBUTING.md file, in your open source repository or site, provides potential project contributors with a short guide to how they can help with your project or study group. It is convention to capitalize the word “contributing” as the file title, and to save it as a resource in markdown (hence the extension .md).

This file is for:

• Project owners - creators and maintainers of the file
• Project contributors - users of the file who want to know items they’re welcome to tackle, and tact they need in navigating the project/respecting those involved with the project
• Project consumers - users who want to build off the project to create their own project [1]

Code of Conduct

Ensure your project has a Code of Conduct, this means not only do you have a CoC, but that you understand, and can communicate how that code is enforced.

Assignment: Set-Up Your Project

• Read Best Practices for Maintainers
• [Create a Wiki Page for your project]
• Select a license
• Create a README.md for your project
• Create a CONTRIBUTING.md for your project.
• Create a Code of Conduct - or reference Mozilla’s Community Participation Guidelines in your CONTRIBUTING.md

Attribution

Mozilla Science Lab - Wrangling Web Contributions: How to Build a CONTRIBUTING.md

next: Writing Good Open Tasks  

Help us improve content and suggest changes to this page.