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 with a group of contributors.

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 3 easy steps are designed to help you create an effective readme file.

Steps to Complete

  1. Write

    Write your README! If you'll need to cover the following points:

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

    If you are having trouble articulating any of these points, and haven't yet created an Open Canvas for your project, we recommend you give it a try. It will help you refine and clarify your thinking about the project, and text from the Open Canvas exercise will help you draft the README.

  2. 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. strong>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.

  3. Re-write

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

  4. 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