Landing Page - README File

Landing Page - README File#

A landing page for your project is the first thing new visitors to your project repository will see. On an online repository, such as GitHub, this landing page is named ‘README’ which is equivalent to the main page of a website.

README files are the welcome mat for your project - it gives you a chance to hook potential contributors and users by showing the value of your project. - Mozilla Open Leadership

To communicate your project effectively and invite your readers to contribute to your project, your README file should cover:

  • What you are doing, for whom, and why.

  • What makes your project special and exciting.

  • How to get started.

  • Where to find key resources.

Think about designing a landing page that is attractive for as diverse readers as possible and provides all the useful information without overwhelming your contributors. For a software project, provide instructions on installation, test, deployment and other requirements for running your software. See this template by PurpleBooth.

For more details, see this presentation by the Open Life Science training and mentoring program. Also, see this short workshop by Hao Ye with a README template to get you started.

Note

Three lessons about README

  • Know your users and what they need

  • Get users doing powerful things quickly

  • Watch out for jargon!

Source: Hao Ye. (2021, March). Collaborations Workshop 2021 Mini-Workshop: README tips to make your project more approachable (Version v1.0.0). Zenodo. http://doi.org/10.5281/zenodo.4647391

Case Study: The Turing Way#

Using The Turing Way README file as an example, we describe what a good README file looks like.

The Turing Way README file includes the following details provided in chronological order:

  1. Project name as the top header.

  2. A set of GitHub badges/shields (You can create your own badge here). GitHub shields are clickable buttons that provide concise actions related to the project, which in The Turing Way include the following: Read the book Join our tinyletter mailing list Join the chat at https://gitter.im/the-turing-way/the-turing-way DOI

  3. Links to the translated version of the README files to allow readers to read it in their preferred language.

  4. One sentence each providing project vision, goal and target audience.

  5. A table to the content providing quick links to different sections of the README file

  6. Different sections with appropriate details and links:

  • About the project: motivation and background

  • The team: who the team members are

  • Contributing: links to contribution guideline and Code of Conduct

  • Citing The Turing Way: instructions for citing the project

  • Get in touch: contact details of the project leads

Finally, we provide a complete list of contributors to the project. This contributors table is updated using the all-contributors bot that acknowledges all kinds of contributions including those that ‘do not push code’.