Code and data guides

Write a README with a reproducible quick start

·

Start with the command a new reader should run and the result they should recognize. A short path from prerequisites to a worked example helps them spot a missing dependency or a path that only exists on your computer.

The Trail Ledger draft shows that path for a sample terminal app. Replace its commands and files with the ones from your own project before you publish.

README Generator

Build the Trail Ledger README and inspect the quick start

Load Trail Ledger example and select Generate README.md. In Setup, expect Python 3.12 or later and three command lines ending in python -m pip install -e . The Usage section contains trail-ledger samples/ridge.csv.

Check that Read a UTF-8 survey file is marked [x] and Import a second survey format is marked [ ]. Markdown keeps these as two task list items. The preview shows the screenshot description, and the source retains docs/trail-preview.png.

Switch off Include a table of contents and generate again. The Contents heading and its links disappear. The Setup and Usage sections and their commands remain.

GitHub Flavored Markdown specificationGitHub documentation on repository READMEs and relative links

Check the commands from a clean checkout

For your own project, list each prerequisite the example uses. Include versions when they affect whether it works. Run the saved installation and usage commands, in order, in a new checkout with the documented shell.

A reader should be able to tell whether the run succeeded. For example, describe the three surveyed routes in the sample spreadsheet or name the generated file. If the fixture must be downloaded separately, give its path before the first command that uses it.

The generator fences commands as code blocks and preserves internal spacing. Command language controls the fence label for syntax highlighting. Run the commands in a terminal when verifying their behavior.

GitHub Flavored Markdown specification

Open the README on the branch that contains its files

Download README.md and put it at the intended location in your repository. Open its rendered view and check each file reference. With a root README, docs/trail-preview.png is under docs. If the README moves into docs, change that link to trail-preview.png or use a repository-root path.

For GitHub status badges, add your owner/repo and enable Include GitHub status badges. The downloaded file contains Shields.io image URLs. Test them in the rendered repository view if the status matters. The local generator shows a text label without loading the badge.

Click the license link in the rendered repository to confirm that it opens the license document you chose. Check links in the same branch as the README so a missing file cannot be hidden by another copy on the default branch.

GitHub documentation on repository READMEs and relative linksShields.io documentation on badge URLs

Common questions

Can I keep the README short and put the rest in docs?

Yes. Leave the optional fields empty to omit those sections. Link to your contribution guide and changelog so readers can find the details when they need them.

What should I verify after removing the table of contents?

Open the rendered README and check the remaining headings. GitHub also offers an Outline menu based on the headings already in the file.

Which URL should I give a screenshot stored with my project?

Use the image path relative to the README, or prefix the path with a slash to refer to the repository root on GitHub. Give the screenshot a short description of the information it adds.

Sources

Put it into practice.

Related guides