• Introducing README files
• Assignment: Write your README

Introducing README files

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.

Assignment: Write your README

1. Draft your README file.

   Use the information you gathered in the Open Canvas exercise as a starting point. Be sure to:

   • Say hello! Welcome people to the project. It’s great to introduce yourself here, so people know they’re dealing with a person or group of real people. Let potential contributors know you’re excited that they’re here to learn more
   • Write a project description: what you’re doing, with who, for who, and why. Sound familiar? This is a version of your project vision. Expand your sentence as a full paragraph, adding any new details about aims and the problems you plan to solve that surfaced in the Open Canvas activity. Try to phrase this so it’s understandable and appealing to a wide variety of people, not just those in your field.
   • Explain what makes your project special, useful, exciting! You can use the ideas you generated for “Unique Value Proposition” in your Open Canvas here.
   • Show how to get started using or contributing to the project. If you’re just getting started, this could be as simple as asking people to attend a planning call or kick-off event, or sign up for an email newsletter about the project. If you’re not sure quite how to get users involved just yet, don’t worry! In the next module, you’ll devise some ways for newcomers to get involved, and create contributor guidelines. Once you’ve done the next module, you can come back to this README and add a link to contributor guidelines to this section.
   • State what resources are most needed. If you have a need for a special kind of help, expertise, or a resource like event space, be sure to mention that here.

2. Test your README for Jargon

   When you’re working in any field, whether it’s software engineering or K-12 education, you’ll learn and use jargon – terms that have a special meaning to your field but likely won’t make sense to anyone who isn’t part of that field. Relying too heavily on jargon can not only confuse newcomers, but it can also obscure detail and prevent even those in the know from coming to a shared understanding of terms.

   As an experiment, copy and paste your project description (what you’re doing, for who, and why, as described in the second bullet point above) and drop it into the Up-Goer 5 text editor. This text editor limits you to only the “ten hundred” most common words in the English language (so-called because “thousand” isn’t one of those common words). See if you can rewrite the description using only allowed words– it’s often harder than it looks. For reference, here is an example of a rocket ship diagram communicated in common language. This specialized text editor is a great way to identify technical language or any other wording that may confuse newcomers. It’s also a good way for you to clarify your understanding of the terms you use. In your final text, you don’t need to restrict yourself to only the most common words, as in the previous step–if you do, your project description may become overly simplified and limited. But you should use what you’ve learned in step 2 to keep your README as understandable and jargon-free as possible.

3. Re-write your README

   Re-write your entire README in clear language and define all terms. If you use jargon, be sure to define those words as clearly as you can, as part of the README text.

   In the next module, you’ll create a Roadmap for your project, a way for you and any potential contributors to keep track of project work that’s upcoming and underway.

Help us improve content and suggest changes to this page.