README? LandingPage

I’ve read a lot of open-source project READMEs lately. Some feel effortless and quickly meet the expectations you have when opening a README. Others feel like a struggle. And some are sparing with words, offering only a brief introduction.

The ones that feel effortless mostly have a simple, clear structure with obvious guidance. The ones that feel like a struggle invariably include detailed installation steps, configuration options, API parameters, and a long string of text that tries to explain the project to death. They’re written with great care, but reading them is painful; like reading a development log. You don’t understand the line under the project name, scroll down to find another screen full of badges, and finally close the page. The documentation may be thorough, but it’s just unreadable.

So I started wondering: what is the purpose of a README? What makes a good one?

The Front Door of a Repository

When I open an unfamiliar repository, I usually don’t read it word by word from start to finish. I first look at the project name and its one-line description, then search for screenshots or code examples, and then decide whether it’s relevant to me. Only if I’m still interested do I look for installation instructions, documentation, and examples.

This process is very similar to visiting a product website.

What the beginning of a README really needs to answer are a few simple questions: What is this? Why should I care? What does it roughly look like? Can I try it quickly?

So a clear positioning statement is often more useful than a row of badges. Screenshots, GIFs, and terminal recordings help readers avoid guessing. What a CLI tool looks like when running, what a component library can ultimately produce, whether a desktop app’s interactions feel smooth; often a ten-second demo is enough. There’s no need to read five hundred words first.

Code repositories also need a bit of “show, don’t tell.” And the more technical the project, the easier it is to forget this.

From another angle, a README is more like a website’s landing page. Of course it needs to provide information, but it also has a more practical task: to catch someone who has just clicked into the repository, has little patience, and knows nothing about the project; and then tell them where to go next.

Progressive Guidance

A landing page doesn’t try to explain the entire product on the spot; it lays out a path. A README should do the same.

The most comfortable reading experience goes something like this: first understand what problem the project solves, then see an example, then get it running in the fewest possible steps. Only after that first success does a reader likely go looking for more detailed configuration, architecture notes, or contribution guidelines.

The “fewest possible” part matters a lot here. A Quick Start is not a condensed version of the installation manual; it’s a quick experience. Copy a few lines of commands and get a clear result. If along the way you need to apply for API keys, modify five configuration files, and understand a directory structure, then it’s not very quick. At the very least, these prerequisites should be stated clearly so people don’t discover something is missing halfway through.

I really like the README of Mole. It has a strong visual impression; it shows the result first. After the project positioning, it immediately presents the terminal interface and disk space savings data. Readers barely need any explanation to understand what it does and how effective it is. Installation takes just one Homebrew command, and common operations are accompanied by real output. It’s especially well-suited for CLI tools.

You don’t need to understand the entire design first; just get the page running and see it in action.

This sense of guidance comes from order. When readers don’t yet know what the project is, don’t start with contribution guidelines; when it’s not running yet, don’t rush to explain internal architecture; when they’ve just become interested, don’t throw an external documentation link at them.

Choosing what to include

READMEs tend to grow longer and longer, and the reason is easy to understand. Every time someone asks a question, you add a paragraph; every time you add a feature, you add another section. Years later, it becomes a mixture of installation guide, FAQ, architecture document, and version history. It has everything, yet the entry point has disappeared.

I now prefer to think of the README as the homepage of a documentation system. It’s responsible for giving the project overview and the shortest path, while details are left to dedicated documentation. When installation hits branching scenarios, readers can go to Getting Started; complex configuration goes to Configuration; design trade-offs and module relationships go into Architecture; and the development environment, testing, and release process contributors need also deserve a separate Contributor Guide.

This keeps things tidy on one hand, and on the other, it serves different visitors with different purposes. First-time visitors want to know if it’s worth trying, existing users need to look up parameters, and potential contributors care about local development. Keeping them all on the same overly long page is clearly inappropriate.

Scalar’s README reads like a complete product landing page. It starts with a one-sentence positioning statement, immediately shows the actual interface of the API Reference and API Client, then provides a minimal runnable example. Readers can see the result, understand the purpose, and try it once without studying the project structure first. More detailed configuration, components, and sub-projects are placed further down; there’s a lot of information, but the reading path isn’t cluttered.

Matching the project’s character

Different types of products usually have landing pages with distinct styles, and I believe READMEs should be no different.

For a command-line tool, the most persuasive content is usually a real command and its output. A library or SDK is better served by a runnable example of about ten lines, letting people quickly grasp what the API looks like. Desktop and web applications should show the interface as early as possible, ideally with a complete interaction visible. Infrastructure projects are hard to explain through screenshots; an architecture diagram, deployment boundaries, and a minimal configuration work better. As for data visualization tools, the result itself is the evidence; notecharts puts chart examples directly on display, and readers can tell at a glance whether it’s what they want.

Some projects should showcase not features but differences. If there are already many similar tools on the market, an honest “Why” is more effective than a generic feature list. It can explain why another one was built, where the trade-offs lie, which scenarios it suits, and which it doesn’t. Clarifying boundaries saves both sides from misunderstandings later.

Adopting the reader’s perspective

I used to treat the README as a cleanup task before delivery. Once the code was written, filling in installation, configuration, and directory structure seemed to complete the job. Now I think the order should be somewhat reversed: first figure out how a stranger would understand the project, then decide what goes into the README.

This is also like building a product. What goes on the first screen, where the demo appears, which step counts as the first success, which link the reader clicks next; these are all experience design. Markdown is plain, but plain doesn’t mean there’s no design.

A good README doesn’t need to explain the entire project. It helps people understand, lets the right people want to try it once, and lets those who aren’t a fit confirm that quickly. Then it sends those who’ve made it this far to the next, more specific document.

At this point, the README’s job is essentially done.