How to Write a Better README Mission Statement

Whether you’re a developer working on a side project or an engineer creating an open source project as part of your job, your goal is similar: To solve a problem that needs solving and to build a community of contributors that extends beyond the original individual or team who started the project.

And yet. There are more than 100 million repositories on GitHub. There is probably something out there that does something similar to your project — at any rate, before your project existed people were solving the problem it solved in some way (or, just as likely, ignoring the problem). If you want to attract contributors or even get people to download your project, it’s important to make it easy to find and clear what type of problems your project solves.

The foundation for building a community around your project is clearly articulating what the project is and what it is good for. Once you know that, it should be the first part of the README, sometimes called the mission statement. It should look like this:

If the project has a website, this information should also be featured very prominently before the scroll. For example:

I took those examples (which I edited slightly) from projects in this list of “Awesome READMEs.” You’ll notice that nearly every entry on the list has “clear description” listed as one of the reasons the README is awesome. The problem for most maintainers is that clearly describing their project is quite a bit harder than one might expect.

Do You Know What Your Project Is?

The challenge for most projects is that what it is is not actually obvious. Many projects don’t fit neatly into already established descriptions, and maintainers don’t always know how to describe what the project does. Users and contributors might — actually often — use the project in a way the original maintainer did not intend. In most cases, there are multiple ways to describe the project that would be accurate, but how you describe it will set the context for what users expect the project to do (and what they do not expect it to do).

If you can’t answer the question “What is Project X?” here are some steps to take to find out what the people who love the project think is the best description.

Identify your top 5-6 contributors. These are the people who see the most value in your project. Then ask them:

• What they use your project for
• What they would do if your project didn’t exist
• How they would describe your project to a colleague
• What they like most about your project

Compare your project with the things the contributors said they would do if your project didn’t exist. Ask yourself:

• What features does your project provide that the alternatives don’t provide? Remember that the alternative could be to ignore a problem or handle something manually — if that’s the case, you’re asking yourself how to compare your project to those options.
• What value do those features provide? Does your project, for example:
  • Save time
  • Prevent errors
  • Increase security
  • Make collaboration easier
  • Or something else…

Once you’ve answered those questions, start by brainstorming different ways to describe your product and pay attention to the assumptions each one elicits. This can involve questions like:

• Is this a platform, a pipeline or a framework?
• What part or parts of the application lifecycle is this project used for?

Going back to the value that your project provides contributors, evaluate each option and see how each potential description aligns with those values. Would it prompt someone to make correct assumptions about what your project does? Does it highlight the unique value that your project provides? Would it make sense to the type of person who should find it useful?

By asking those questions, you should come up with a clear description for your project that makes sense to the type of person you’d like to use and contribute to your project. If the description is more than 20 words long, you should try again. And resist the temptation to label your project with a brand new term that no one else will understand.

Writing a great mission statement for your README is about finding a way to instantly create a context for your project that will highlight its strengths and make its value obvious. This is how you grab attention for your project among the sea of repositories, and how you make sure that a higher percentage of people who download the project use it and become contributors down the line.

Feature image from Gerd Altmann de Pixabay.

Emily helps open source startups accelerate revenue growth with killer positioning. She writes about entrepreneurship for engineers, and hosts The Business of Open Source, a podcast about building open source companies.

Read more from Emily Omier