---
title: "Landing Page - README File"
source: The Turing Way
source_url: https://github.com/the-turing-way/the-turing-way
licence: CC-BY-4.0
domain: data-and-analysis
subdomain: turing-way
date_added: 2026-04-25
---

(pd-project-repo-readme)=
# 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](https://mozilla.github.io/open-leadership-training-series/articles/opening-your-project/write-a-great-project-readme/)

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](https://github.com/PurpleBooth/a-good-readme-template).

For more details, see [this presentation](https://docs.google.com/presentation/d/e/2PACX-1vTvwtT3GddLaDr8J4ZEf8TkufiN_Wn1Kgv2xu6YSH8hgocb6LJ_WB82OzfcPeJ0b09_xyMOMSft7-Gq/pub?start=false&loop=false&delayms=3000) by the [Open Life Science](https://openlifesci.org/) training and mentoring program.
Also, see this [short workshop by Hao Ye](https://ha0ye.github.io/CW21-README-tips/) with a [README template](https://ha0ye.github.io/CW21-README-tips/template_README.html) 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](https://github.com/the-turing-way/the-turing-way/blob/main/README.md) 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](https://github.com/badges/shields) (You can create your own badge [here](https://shields.io/)).
GitHub shields are clickable buttons that provide concise actions related to the project, which in _The Turing Way_ include the following:


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](https://allcontributors.org) that acknowledges all kinds of contributions including those that 'do not push code'.
