[Project name]

[One sentence: what it does and who it is for]

Fill in the name, the first line, Installation, Usage and License first. Keep the other sections your project needs and delete the rest. Replace the blue placeholders, delete the grey notes, then export to Markdown and save the file as README.md in the project's root folder.

Status

[Active / maintenance only / archived]

Latest release

[x.y.z, YYYY-MM-DD]

Runs on

[Platforms or runtime, with minimum versions]

License

[License name, such as MIT]

Maintainers

[Names, or the owning team and its chat channel]

See a weak first line next to a strong one

Weak: A blazing-fast, modern toolkit that supercharges your workflow.

Strong: Turns straight quotes into typographic quotes in Markdown and HTML, without touching code blocks.

The strong one names the job and the one thing it won't break. Reuse it as the repository description.

Features

  • [What it does, as something a user would notice]

  • [A second thing it does]

  • It does not: [what it deliberately leaves out]

Requirements

  • [Platform or runtime, with the minimum version]

  • [Accounts, keys or services it needs]

Installation

  1. Install: [the install command]

  2. Check: [a command that proves it worked]

You should see: [what success looks like, such as the version number]

Run every command on a clean machine. Copy commands from the terminal, not from memory, and say what success looks like under each one.

Usage

[The smallest command or code snippet that does something useful]

Output: [what the reader should see]

Configuration

Setting

Default

What it does

[Name]

[Default value]

[One line]

[Name]

[Default value]

[One line]

Environment variables: say which are required. Real keys never go in the README; use placeholders and an .env.example file.

Documentation

  • Tutorial: [link]

  • How-to guides: [link]

  • Reference: [link]

  • Changelog: [link]

Getting help

  • Questions: [where to ask]

  • Bugs: [where to report them, and what to include]

  • Security problems: [how to report them privately]

Contributing

[How to set up a development copy and run the tests]. Details in [link to CONTRIBUTING.md].

License

[License name] © [Year, name]. Full text in [link to the LICENSE file].

For a dataset: sections to use instead

For research data, replace Installation, Usage and Configuration with these five sections, and save the export as plain text, README.txt. For many data files, repeat the last section for each one.

General information

[Title; investigator, institution and email; dates of collection (YYYY-MM-DD); location; funding]

Sharing and access

[License; recommended citation]

Data and file overview

[Each file and what it holds; how the files relate]

Methods

[How the data was collected and processed; software and versions; quality checks]

Data-specific information

[Per file: number of rows and variables; each variable with units; codes for missing data]

Before you publish

  • The first line says what the project does and who it is for

  • Every command was run on a clean machine, with what success looks like

  • No real keys, passwords or connection strings anywhere

  • Every heading has content; unused sections are deleted

  • Links are relative, and every one works

  • The status, the license and a way to get help are on the page