---
title: "Welcome the next person to a project."
description: "Write a README that explains purpose, first use and where to ask for help."
canonical: https://editmd.app/learn/lessons/readme/
markdown: https://editmd.app/learn/lessons/readme.md
status: pre-release, waiting list open
generated: editmd-website
---

# Welcome the next person to a project.

Lesson 17 of 18 in Markdown School. Write a README that explains purpose, first use and where to ask for help.

## Answer a newcomer’s first questions

A README is often a project’s introduction: what it does, how to begin and where to get help. GitHub describes those uses in its [README guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). It is a filename convention, not a special executable format.

This fictional project is just a folder of garden records. A file called `notes.md` already exists. There is no application to install and no terminal command to run. Start with [headings](/learn/lessons/headings/) and [code fences](/learn/lessons/code-fences/) before this project.

## Show a real first use

````markdown
# Garden notes

A folder of garden records.

## Start

Open notes.md in a text editor.

## Use

```text
Water seedlings
```

## Help

Ask the project maintainer.
````

The Start section tells the reader what to open. Use supplies a small example they can add. Help identifies a route to a person without inventing contact details. A real project can link to its actual support channel once that destination is known.

## Match the instructions to the project

A convincing-looking `npm install` command would be wrong for this folder. Do not add setup commands, compatibility promises, licence claims or badges merely because other READMEs have them. Test real instructions in the environment you describe, and record prerequisites when they exist.

An AI assistant can draft sections from supplied facts. Review each claim and command against the actual project before publishing. Keep secrets, private paths and personal information out of copyable examples.

## Practise a useful example

Add Use between Start and Help. Put Water seedlings in a `text` code fence. The checker looks for the introduction, populated sections and that example. It does not open a project or test installation.

[Download a fuller README template](/learn/examples/project-readme.md) and replace its fictional details. Keep only sections that help your reader.

## Exercise

Add a Use section with a fenced text example containing Water seedlings. Keep the supplied Start and Help sections, and do not invent an installation command.

## Takeaway

A README should give the next reader a truthful first step.

Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md