Skip to content

Latest commit

 

History

History
73 lines (53 loc) · 3.22 KB

write-a-readme.md

File metadata and controls

73 lines (53 loc) · 3.22 KB
Raw

Creating a welcoming README

When you create 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.

As we have seen GitHub gives a special role to the file named README.md. This makes it very visible and hence a good place to welcome people to your project.

For a project that is only used within your lab (or even just by you) it is still a good idea to list what the project does, how to install and use it. It will help you in three months time (or after a holiday) and encourages others to try out your project, and then they might contribute! The act of writing out what the project does will also help you stay focussed when adding new things.

The following 3 easy steps are designed to help you create an effective readme file.

Write a README

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

  • 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 are looking for
  • Point to other key resources, such as a contributing.md file and a roadmap.

Examples of READMEs that I like:

Note: have you commited your changes?

Remove jargon

The US space team's Up goer five. Copy and paste the description of your project into http://splasho.com/upgoer5/. How many words do you have to remove?

Exercise: can we describe "decentralised internet" without using words that are too complicated?

Try and re-write your project description so that it passes the "up goer five" test. While you might not want to use that description in reality it will make you aware of jargon and complex words that might be worth replacing.

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.

Re-write your readme

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

Make sure to use Git along the way. Use git add to add a file you changed, git commit -m "My message here" to record the changes, and git push to store changes on GitHub.