Open Project Communication

Create a useful and welcoming readme file for your open project.

For beginners

Format

This exercise works well as an in-person or online exercise. You can work alone, or in a group.

Target Audience

Project leads

Materials

  • A computer and an internet connection.
  • An open project you want to tell people about.

Introduction

When you open your project, you may have a specific audience in mind (for example, software developers or other researchers in your field)... but you can reach a much broader community! Many people outside of your field-- designers, technical writers, citizen scientists-- may be interested in your project and have valuable contributions to offer! Clearly communicating information about your project in simple language is an excellent way to grow and diversify your community.

The readme file is one of the first things you add to your project repository. It introduces your project idea and goals. Along with the contributing file, the roadmap, and your Code of Conduct, the readme file helps welcome, orient, and encourage newcomers to participate.

The following steps are designed to help you create an effective readme file. First, you'll use a tool called Open Canvas to define and organize key information about your project. Then you'll write a readme file and test it for clarity, using an online text editor that encourages the use of simple language.

Steps to Complete

  1. Create an Open Canvas for your project

    Open Canvas is adapted from Lean Canvas, a one-page format used for describing a start-up business project. Open Canvas helps you clarify the problem you aim to solve, the solution you propose, and what is especially valuable about your open project. It also helps you define your users and contributors, measurements of success, and any resources you'll need.

    Here is an example of an Open Canvas grid filled in for the Mozilla Science Lab's Paper Badger Project:

    Here is a link to a Google Sheets version of the Open Canvas you can copy and edit online. Go to File > Make a copy... to start editing.

    Here is a link to download a pdf version of Open Canvas.

  2. Write

    Using the information you gathered in the Open Canvas exercise, write your readme file. Be sure to:

    • Say hello! Welcome people to the project.
    • Show what you're doing, for who, and why.
    • Explain what makes your project special, useful, exciting!
    • Show how to get started using or contribution to the project
    • State what resources and contributions you're looking for
    • Point to other key resources, such as a contributing.md file and a roadmap.

  3. Remove Jargon!

    Copy your new project description (what you're doing, for who, and why) and drop it into the Up-Goer 5 text editor. Try to rewrite the description using only allowed words. This is a great way to identify technical language that will confuse newcomers. For reference, here's an example of a rocket ship diagram communciated in common language.

    In your final readme text, don't restrict yourself to only the most common words--if you do, your project description may become overly simplified and limited. Use what you've learned from this exercise to keep your readme as jargon-free as possible. If you use jargon, be sure to define those words.

  4. Re-write

    Re-write your entire readme in clear language and define all terms. Share your new readme in your project repository.

Glossary

Readme file

a document that introduces an open project to the public and any potential contributors.

jargon

a type of language, especially vocabulary, that is particular to a certian trade or discipline, and is not understood by anyone outside that discipline.

repository or repo

a collection of documents related to your project, in which you create and save new code or content.

Follow-up Resources & Materials