Skip to content

Blog

How to write a good README: four questions every visitor asks

A good README answers four questions on the first screen: what this is, whether you can use it, how to install it and how to help. Write those answers first and in that order, and move everything else into other files.

By
GitWow editorial team
Updated
updated
Reading
7 min read

Order the README by the visitor's questions: what is it, can I use it, how do I install it, how can I help.Put the value in two lines and one visual before any installation steps.Keep only what a newcomer needs to start and contribute, and move the rest to docs or the wiki.Badges, GIFs and a contents list stay only when they answer one of the four questions.

In 10+ years of growing accounts, with more than 10 billion in reach, the first screen has decided more than anything placed below it. A README is that first screen for a repository.

Two of our free tools write the first draft. Our README generator reads a public repository and returns a README.md with badges, quick start and license, and our badge generator builds live badges for stars, forks, license and releases. This page covers what to check once the draft exists.

The file deserves the time. GitHub's documentation says a README is often the first item a visitor sees. At GitWow, members star and follow each other's public repositories by hand, and a star makes a repository look alive to the next visitor. That visitor stays for the code and the README. Good content grows any account, and on a repository the content is the README.

A README works as a first screen that answers four questions

Most guides list the same sections: title, description, installation, usage, contributing and license. The sections are right. What helps is tying each one to the question a visitor brings, because then you can see what is missing and what can go.

Visitor's questionSection that answers itWhat goes there
What this isName and two-line descriptionThe problem solved and who it is for
Whether I can use itVisual, quick start, licenseA result on screen, a first command, the terms of use
How to install itRequirements, installation, usagePasteable commands and the simplest working example
How to helpContributing, contactsHow to fork, where to ask, who maintains the project

GitHub's own list covers the same ground: what the project does, why it is useful, how to get started, where to get help and who maintains it. A heading that answers none of the four belongs in another file.

What to do now: open your current README and write the matching question next to each heading. Headings left without a question are the first to move out.

Name the project and say what it does in two lines

The first heading is the project name, and the two lines under it state what the project does and who uses it. The description appears on 14 of the 36 guides we read for this page and the project name on 11, and visitors read both before anything else.

  • Pick a name that explains itself, or add a short phrase after it.
  • Lead with the result the project gives, and leave its history and motivation for later.
  • Use the words your user would type into a search box, which also helps people find the repository (see GitHub repository SEO).

A fill-in form that works for most projects: {name} is a {what it is} for {who}. It {does what}, so you can {result}.

What to do now: write both lines, read them to a colleague outside the project, and ask who they think it is for. If the answer is wrong, rewrite the lines.

Show the result before the setup

A visitor who sees the result in the first screen reads the installation section with a reason. A screenshot, a banner or a short GIF does the job. The author of a widely shared dev.to guide, a former COO of AFFiNE (60k+ stars), argues that the README has to convert the visitor and that a quick start belongs right after the description. That is the author's view and we have no measurement of our own. It matches how a first screen reads.

  • Place the visual under the two-line description.
  • Keep GIFs small: the Ultimate Project README template states a 10 MB maximum size.
  • Put a quick start of two or three commands before the long explanations.

What to do now: record the shortest run of your project that ends in something visible, and put it under the description.

Write installation as commands someone can paste

Installation is one of the two most common sections in the guides we read, with 18 of 36. Requirements come first, listed in the order a person meets them, then one code block per step, each ending with what the person should see.

  1. List requirements: operating system, language version, dependencies.
  2. Give each step as a command in a code block, such as git clone, then cd, then the install command of your tool.
  3. State the expected output after the last command.
  4. Add a separate block for each operating system that needs different commands.

What to do now: clone the repository into an empty folder and follow your own README line by line. Every step you fix is a step a visitor would have failed on.

Show usage from the simplest case

Usage answers whether the project does the job. Start with the smallest example that runs, show its output, then add the harder cases. A line with the command that runs the tests shows a visitor the project is maintained.

What to do now: paste the smallest working example into the README and run it once from the file.

Say how to help and which license applies

Contributing appears in 18 of the 36 guides we read and license in 13. The contributing part describes how to fork, set up and open a pull request, and links to a CONTRIBUTING file for longer rules. The license part names the license and links the LICENSE file. GitHub's documentation describes the README, license, contribution guidelines and code of conduct together as the files that set expectations for a project.

  • Say in one or two friendly sentences that contributions are welcome and where to start.
  • Name the license in the README and keep the full text in a LICENSE file.
  • Add a contact: an issue tracker, discussions or an address.

What to do now: add the three lines above and link your CONTRIBUTING file if you have one. Our forks page covers the other side, when you want people to fork the project.

Keep the README short and move the rest out

GitHub's documentation says a README should hold the information developers need to get started and to contribute, and that the rest can live elsewhere. Two common pieces of advice disagree with each other, and the table shows where each one comes from.

TopicOne answerAnother answer
Length500 to 1,500 words is the sweet spot, per the dev.to author aboveGitHub has no word limit, and it truncates content beyond 500 KiB when the README is viewed on GitHub
Contents listWrite one by handGitHub builds one from your headings in the Outline menu of any rendered Markdown file
File locationRoot folderThe .github folder, the root or docs, and GitHub shows them in that order if there are several

Plain version: a word count is advice from one author, while the 500 KiB cut-off is a rule of the platform, so write for the reader and stay far below the rule.

For what leaves the README, GitHub's blog suggests splitting documentation by purpose into tutorials, how-to guides, explanation and reference. A wiki, a docs folder or an ARCHITECTURE.md file each take one of those, and the README links to them.

What to do now: find the longest section in your README and ask whether a newcomer needs it to start. If not, move it to docs and leave one link behind.

Badges, GIFs and a contents list help only when they answer a question

A badge answers whether the project is in a working state. Build status, license, version and test coverage do that. Decorative badges only push the description down. Keep the three or four that show a real state, and build them with the badge generator. GIFs show what the project does, as covered above.

A contents list shows where the needed part is. For a short README the heading structure is enough, and for a long one the Outline menu on GitHub covers moving around. Add a hand-written list only if the file is displayed outside GitHub.

Two formatting habits pay off. Use relative links and image paths, which GitHub rewrites for whichever branch you are viewing, and give code blocks a language name so they get highlighting.

What to do now: remove every badge you cannot explain in one phrase.

Check the README with a checklist before you publish it

  1. The first two lines say what the project does and for whom.
  2. A visual sits in the first screen.
  3. Installation commands work from an empty folder.
  4. The simplest usage example runs.
  5. Contributing and license are present.
  6. Every link opens, including links to files that moved.
  7. No section is a wall of text without a heading.

The mistakes the guides name are a missing description, missing install steps and examples, a wall of text and outdated links. If you want an AI draft, GitHub Docs publishes a README prompt for Copilot (public preview). The result still needs your edits, because only you know who the project is for.

Once the README is ready, give the next visitor a reason to stay

A README that answers the four questions turns a visit into a decision. After that, share the repository: GitWow members star and follow public repositories by hand from their own accounts, and nobody asks for a GitHub password, token or OAuth, only the public link. The first request is free. Add your repository when the README is done.

Next steps: write the one-line repository description and topics with the repository description generator, then read the guide to getting a project noticed and how to get GitHub stars. A README for your own profile is a different file, covered in the profile README guide.

FAQ

Frequently asked questions

How do I write a good README?

Answer four questions in order: what the project is, whether the visitor can use it, how to install it and how to help. Put the value in two lines and one visual first. GitHub's documentation notes that a README is often the first item a visitor sees.

What should a README include?

A project name, a two-line description, a visual, installation, a simple usage example, a contributing note and the license. GitHub's documentation lists the same ground: what the project does, why it is useful, how to start, where to get help and who maintains it.

How long should a README be?

GitHub sets no word limit and truncates a README beyond 500 KiB. One dev.to author suggests 500 to 1,500 words as advice. Keep what a newcomer needs to start and link the rest.

What is a good README template?

Start from our README generator, which writes a draft for a public repository. Best-README-Template is a popular community template, and its repository shows 22,898 forks. Whichever you pick, cut every section that does not answer one of the four questions.

Do I need a table of contents in my README?

A short README does fine with its headings alone. GitHub builds a table of contents from your headings for any rendered Markdown file, and it opens from the Outline menu. Add your own only if the file is shown outside GitHub.

How do I add badges and GIFs to a README?

Paste the Markdown of each badge under the title. The badge generator gives it for stars, forks, license and releases. For a GIF, keep the file small: the Ultimate Project README template states a 10 MB maximum.

Can AI write my README?

It can write a draft. GitHub Docs has a README prompt for Copilot in public preview, and our README generator also drafts one. Edit the result against the four questions, because the draft does not know your audience.

Related pages

PageSectionUpdated
GitHub profile README: make it show, keep it short, keep it freshBlog
Free GitHub Badge GeneratorFree tools
Free GitHub Profile README GeneratorFree tools
Free GitHub README Stats GeneratorFree tools
GitHub achievements: every badge, its tiers and how to earn itBlog
GitHub contribution graph: what counts and why yours is emptyBlog

GitWow is a free community for growing your GitHub repositories and profile with help from other members.

Start free

47k members ยท 900+ actions a day