# How to Write a README That Actually Gets Read > A README is the first thing a visitor sees. Most READMEs are walls of text that nobody reads. The good ones are short, scannable, and answer the four questions every visitor has: what is this, why should I care, how do I use it, and how do I install it. Here is the structure, with examples. URL: https://uttir.com/blog/how-to-write-a-readme-that-actually-gets-read Published: 2026-08-22 Author: Uttir Reading time: 6 min Tags: documentation, developer-tools, writing, open-source, essay ## Quick answer A good README has seven sections in this order: title with one-line description, why (the problem it solves), screenshot or demo, install (one or two commands), usage (the smallest working example), API or options reference (only the essentials), and contributing or license. Skip the badges, the contributor wall of photos, the giant feature list, and the philosophical introduction. Aim for under 500 words of prose; everything else is in code blocks. The [Uttir Word Counter](/word-counter) can tell you when you are over. You open a repository. The first file is README.md. You start reading. Three paragraphs in, you still do not know what the project does. Five paragraphs in, you find a list of features that are mostly internal jargon. You close the tab. The project lost you, the same way it loses most visitors. A README is a sales page for a software project. The visitor is asking four questions, in this order: what is this, why should I care, how do I use it, and how do I install it. The README has about 90 seconds to answer all four. If it does, the visitor stays. If it does not, the visitor leaves and never comes back. ## The seven sections, in order Every good README I have seen has the same structure, in the same order. The order is not arbitrary; it matches the order of questions the visitor is asking. Skipping a section or rearranging them is a small sin, but doing both is a large one. ### 1. Title and one-line description The first heading is the project name. The first paragraph is a single sentence that says what it is. Not what it does internally, not what stack it uses, but what it is for. "A command-line tool that converts HEIC photos to JPG without uploading them" is good. "A HEIC to JPG converter written in Rust" is bad — it tells you the language but not the value. For most projects, the one-line description is the most important sentence in the README. Visitors who read no further will still have a correct mental model of what the project is for. ### 2. Why (the problem it solves) Two or three sentences on the problem. Not the implementation, the problem. "Most HEIC converters upload your photos to a server, which is slow and a privacy concern. This tool runs entirely on your laptop, so the photos never leave your device." That is the problem. The visitor now knows whether this is for them. Skip the philosophical introduction. "In an era of ever-increasing media capture, the need for efficient format conversion is paramount" is two sentences that say nothing. Visitors do not care about your introduction; they care about whether the tool solves their problem. ### 3. Screenshot or demo A picture is worth a thousand words. A 5-second animated GIF is worth a thousand pictures. The screenshot should show the tool in action, with the input on one side and the output on the other, in the most common use case. A terminal recording (using `vhs` or `asciinema`) for a CLI tool; a screenshot of the main UI for a web app; a short video for a desktop app. Keep the screenshot small (under 500 KB) so the README loads fast. Link to a higher-resolution version if the visitor wants more detail. ### 4. Install One to three commands. The exact commands to install the tool on the most common platforms. For a CLI tool, this is usually a Homebrew command, a curl-pipe-bash, a download link, or a package manager install. For a web app, it might be a deploy button. For a library, it is a package manager command (npm install, pip install, cargo add). Put the most common install command first. If the tool is most often installed via Homebrew, put the Homebrew command first and the others below. Do not make the visitor scroll past three platforms they do not use to find the one they do. ### 5. Usage The smallest working example. For a CLI tool: the command and its output. For a library: the smallest code snippet that does something useful. For a web app: the URL to visit and what to do there. One example. Not five. The visitor is trying to verify the tool works; the smallest possible verification is the goal. Additional examples go below, in a separate section. ### 6. API or options reference The full list of options, flags, configuration values, or API endpoints. This is the reference section, the part the visitor scans when they already know they want to use the tool and are looking for the specific flag or option they need. Tables work well here. Auto-generate this section from the tool's help text if possible; the section is the most likely to go stale. Keep the reference complete but not verbose. One line per option: the name, the type, the default, and a one-sentence description. If an option needs more explanation, link to a separate docs page. ### 7. Contributing and license How to contribute. A CONTRIBUTING.md file linked from this section is the standard pattern. The license (MIT, Apache 2.0, GPL) and the copyright holder. If the project has a code of conduct, link to it here. For most open-source projects, the contributing section is two sentences: "Open a PR. Run the tests." The detailed contribution guidelines (style guide, branch naming, commit message format) go in CONTRIBUTING.md, not in the README. ## What to leave out Eight things that are common in bad READMEs and should be cut: - **The badge wall.** Six rows of badges (build status, coverage, version, license, downloads, stars) at the top of the README. Visitors do not care. Pick the one or two that actually matter (build status for a library, version for a CLI) and put them inline with the relevant section. - **The contributor photo wall.** A grid of avatars of everyone who has ever contributed. This is a nice gesture but it pushes the actual content down. Link to a CONTRIBUTORS file instead. - **The "Features" list.** A 20-item list of features, most of which are obvious from the tool's name. "Supports HEIC", "Outputs JPG", "Fast", "Free" — these are not features, they are table stakes. Cut the list or move it to a section below the install. - **The "Built with" section.** A list of every dependency. This is what package.json is for. The visitor does not need to know that you use lodash. - **The "Roadmap".** A list of features you might add someday. This goes in a separate ROADMAP.md, not the README. - **The "Acknowledgments".** A long thank-you list. Put it at the bottom, in three lines, with links to the people or projects. - **The "FAQ".** If the README has a FAQ section, the README is too long. The FAQ is the README, and the README is the FAQ. Cut one. - **The "Support".** A long list of support channels (Discord, Slack, email, GitHub Discussions, Stack Overflow). Pick one or two and link to them in a single line. ## How long the README should be Under 500 words of prose for a small project. Under 1500 words for a medium project. Over 2000 words and you should split: the README becomes a landing page, the docs move to a separate site (or a `/docs` folder). The [Uttir Word Counter](/word-counter) will tell you when you are over. The [Reading Level](/reading-level) tool will tell you whether your prose is at the right level for the audience (aim for grade 8-10 for a developer audience; lower is rarely a problem, higher is). ## Markdown, not HTML Write the README in Markdown, not HTML. Markdown renders correctly on GitHub, GitLab, Bitbucket, SourceHut, and every other code host. HTML renders correctly only on the host you wrote it for. The conversion from Markdown to HTML is the host's job, not yours. The one exception: if you need a specific layout (a centered logo, a custom callout box, an embedded video), use a tool that supports extended Markdown (like `markdown-it` with plugins, or MDX for a docs site). Do not embed raw HTML in a GitHub README — it gets stripped. ## When the README is the wrong format For a library with many functions and a complex API, the README is not enough. The reference docs go on a separate docs site (Read the Docs, GitHub Pages, Vercel). The README becomes the landing page that points to the docs. For a tutorial-style project, the README is not enough. The tutorial goes in a separate file or on a separate site. The README becomes a one-paragraph description and a link to the tutorial. For a tool with a graphical UI, the README is not enough. The user manual goes in a separate file. The README becomes the quickstart and a link to the manual. The README is the front door. The docs are the rest of the house. Both are needed; they serve different purposes. ## Related tools - [Word Counter](https://uttir.com/word-counter) — Count words, characters, sentences, and paragraphs in your text instantly. - [Reading Level Calculator](https://uttir.com/reading-level) — Check how hard your text is to read. Six readability formulas (Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog, SMOG, Coleman-Liau, Automated Readability Index) in one tool, all in your browser, no upload. - [Markdown to HTML Converter](https://uttir.com/markdown-to-html) — Convert Markdown to clean HTML. Headings, lists, links, images, code blocks, blockquotes, and inline formatting. - [JSON Formatter](https://uttir.com/json-formatter) — Format, beautify, and validate JSON with adjustable indentation — instantly in your browser. - [UUID Generator](https://uttir.com/uuid-generator) — Generate cryptographically random UUID v4 identifiers, one or a thousand at a time. --- For the full HTML article, visit https://uttir.com/blog/how-to-write-a-readme-that-actually-gets-read. This file is the markdown rendering at https://uttir.com/blog/how-to-write-a-readme-that-actually-gets-read.md. See https://uttir.com/llms.txt for a site-wide summary.