README Template for a Launch: What the Top of Your Repository Page Must Say
A launch README answers four questions before the reader scrolls: what is this, why would I want it, how do I run it, and is it alive. Put a one-line description, a working install-and-run snippet and one picture or output sample on the first screen, then add details below. Templates follow for a library or command-line tool, for an app that people run themselves, and for a status and contributing block.
What does a stranger read first on a repository page?
The README is the page a repository shows under its file list, so for a developer tool it is also the landing page. A visitor who arrives from a launch post, a thread or a search result gives it about as long as they would give any front page: a glance at the top, then a scroll if the top earned it. That first screen is where the README succeeds or fails.
Put these on it, in this order: the project name and a one-line description in plain nouns, one proof that it works (a screenshot, a short recording, or a sample of real output), and the shortest working way to try it. Everything else, including architecture, configuration and history, can wait below. A reader who cannot run it in a couple of minutes will usually not come back for the architecture.
Template 1: a library or command-line tool
# [project-name] [One sentence: what it does, for whom, in plain nouns.] [One screenshot, terminal recording or code-and-output sample showing it working.] ## Install [the exact install command, copied from a clean machine] ## Quick start [the smallest complete example that runs: input, command, expected output] ## Why this exists [Two or three sentences: the problem, why existing tools did not fit, what you chose to leave out.] ## Usage [The three most common tasks, each with a short example. Link to full docs for the rest.] ## Compared with [alternative tool] [Two honest sentences on when to use the other one instead.] ## Status [Alpha / beta / stable]. Tested on [platforms and versions]. Known gaps: [list]. ## Licence [Licence name and a link to the file]
The comparison section is optional but earns trust. Naming a better-suited tool for a certain case shows you understand the field, and readers who leave to try the other tool will remember you kindly.
Template 2: an app people run themselves
Self-hostable and desktop apps have a different reader, who wants to know what it looks like and what it needs before installing anything. Lead with the picture, then the requirements, then a setup path that does not assume they know your stack.
# [App name] [One sentence: what it is and who uses it.] [Screenshot or short recording of the main screen.] **Try it without installing:** [demo link, or "no hosted demo yet"] ## What you need - [Runtime, operating system or container tool, with versions] - [Storage or accounts it uses, and whether any data leaves your machine] ## Run it 1. [Get the code or the release file] 2. [Set the one or two required settings; show the example file] 3. [Start command] 4. Open [address] and [first thing to do] ## What it does today - [Capability one] - [Capability two] ## What it does not do - [Limit one, and whether it is planned] ## Updating and backups [How to update safely and where the data lives.] ## Help [Where to ask, how fast you reply, how to report a bug with the details you need.]
Template 3: a status and contributing block
People deciding whether to depend on a project look for signs of life and for how you handle outside help. A short honest block does both. It is the part most launch READMEs skip, and the part skeptical readers read twice.
## Project status I build [project name] [in my spare time / full time]. Releases are [roughly every N weeks / when something is ready]. The latest is [version] ([date]). ## Contributing Bug reports with steps to reproduce are the most useful thing. Before opening a pull request for anything bigger than a small fix, please open an issue so we can agree on the approach. I try to reply within [time], and I may say no to features that don't fit the scope in "Why this exists". ## Security Found a security problem? Please report it to [private address or form] and not in a public issue.
Which README mistakes cost the most readers?
- An install command that does not work on a clean machine. Test it in a fresh container or a new user account before you launch. This is the single most common failure.
- A quick start that needs three other steps first. Move the prerequisites above it or make them unnecessary.
- A badge wall at the top. Two or three badges that mean something (build status, licence, version) are fine. Twelve push the description below the fold.
- Features without a sample. “Supports transforms” says less than five lines of input and output.
- No licence. Without one, others cannot legally use the code in most places. Choose one and add the file.
- A story before the install. The journey is interesting after the reader has run it, not before.
What goes around the README on launch day?
A changelog from day one, as in the changelog template; a demo recording from the demo video script template; and a post written for the place you will share it, such as the Show HN templates, whose guidelines ask for something people can try. The wider checklist for projects like this is the open source launch checklist, and the open source playbook covers the sequence. For a public page that links to the repository, launch your project free here, with the repository as the website link. Builders in this area can scan the board’s developer tool ideas for gaps that need a good first README.
Frequently asked questions
How long should a README be?
As long as the reader needs to run the project, and no longer. A small tool may need under a page; a larger one can link to separate docs. What matters is that the first screen has the description, a proof and the quickest way to try it, and that the rest is organised under clear headings.
Do I need a screenshot or GIF in the README?
If the project has anything visual, yes, since one image explains what a paragraph cannot. For a library or command-line tool, a short code sample with its output, or a terminal recording, does the same job. Keep the file small enough to load quickly, and make sure it shows a real use.
Should the README include a comparison with other tools?
A short, fair one helps. Readers are already comparing, and an honest line on when to choose another tool builds trust. Avoid tables that make every competitor look bad or claims you cannot support. If you are unsure of a competitor’s current features, say less or link to their page.
What licence should I choose for a launch?
Pick one deliberately and add the file; the choice affects how others can use your code. Many small projects choose a permissive licence, but you should read the options and, if the code matters commercially, take legal advice. This site cannot advise on licences. No licence at all usually means others cannot reuse your work.
Written by Post your build ideas with AI assistance and edited for this site. Where a page names another product, the facts came from that product’s own pages on the date shown above; terms change, so check them before you rely on them. About the publisher.