README as the project interface

1. Introduction

README is usually read before the code. And this is not a joke, but a harsh engineering reality: a person clicks a repository, sees the first page, scans it, decides “do I need this?”, and either stays or leaves to look for another project. That’s why README is part of the interface: it does not compile, but it gets “called” by people constantly.

If you need an even more pragmatic motivation: the Go ecosystem really uses README as display material. For example, the pkg.go.dev infrastructure, while processing modules, extracts README and other documentation—meaning your README literally becomes the public face of the package.

README is not a textbook and not a developer’s internal diary. A good README answers the questions “what is it?”, “how do I run it in a minute?”, “how do I use it correctly?”, and “if it breaks, what are the boundaries of responsibility?”. It also saves you time: fewer repeated questions in chat/issues, fewer “how do I run it?” on calls, and less magic when you come back to the project a month later.

Who reads the README, and in what mood

To write a README thoughtfully, it helps to imagine the reader. Usually it’s one of three people: future you (who forgot how everything works), a colleague (who needs to run and verify quickly), or an external user (who is not obligated to understand your architectural poetry at all). All of them share one resource: limited attention.

So the main rule of README sounds almost like a rule for a good sign at a coffee shop: “so that a person understands what you sell before they open the door.” Don’t make the reader jump through links and guess where the entrance is. README should provide quick success: run it—see the result—trust the project.

If README turns into a long story of “how we chose an ORM and argued about spaces,” it starts working against the project. That story is normal, but it belongs in another document (for example, docs/), not on the main page.

2. Minimal README structure

You can write a README in different ways, but it has a “minimum skeleton” that makes the document useful almost always. I deliberately say “skeleton,” because this is not a list of 50 sections and not a 12-screen template—it’s a few key blocks without which the reader will stumble.

Below is a table of “what is usually needed” and “why it matters at all”:

Note a subtle point: README is not the place where we describe “every function.” API details live in GoDoc, which is pulled into pkg.go.dev and IDEs. And README is the “route to the entrance” and the “map of the territory,” so a person doesn’t wander through the code like through a forest without a compass.

3. Quickstart: how to deliver a “first success in 60 seconds”

Quickstart is the most important section of a README. It must be so short and direct that the reader has no time to get scared. A good quickstart is like a “Demo” button in a game: you click it, see that the world exists, and only then start figuring out where the inventory is.

Let’s be practical and tie the README to our educational project. Suppose we have a mini app Tasky: a simple console todo app where you can add a task, show the list, and mark one as done. Storage is in memory for now—yes, it’s not “production-ready,” but it matches our level and current topics.

Let’s imagine the repository structure (we’ll return to it in “architecture”):

tasky/
  cmd/tasky/main.go
  internal/todo/service.go
  go.mod
  README.md

Now the quickstart in the README should look roughly like this (this is not a Markdown lecture, so we keep it concise):

## Quickstart

Requirements: Go 1.25+

Run:
```bash
go run ./cmd/tasky
```

Example session:
```text
> add Buy milk
ok: added task #1
> list
1 [ ] Buy milk
> done 1
ok: task #1 marked as done
```

Three things matter here. First, the Go version: you pin expectations. Second, one run command, without “first install 8 utilities and configure 3 environment variables.” Third, an example of the result—so the person knows what they should see; otherwise they’ll run it, see an empty screen, and decide the project is broken.

5. Usage examples

Usage examples are where a beginner usually falls into one of two extremes. The first extreme: no examples at all, only “this is a library for working with tasks.” The second: 200-line examples that mix input, output, business logic, error handling, flags, configs, and in the middle a philosophical treatise on the meaning of life context.Context.

The right middle is this: 2–4 short scenarios, each about one idea. For our Tasky, we can show an add scenario, a list scenario, and an error-handling scenario (for example, “bad id”). The example should reflect Go style: error checking is part of the normal path, not an “exception to the rule.”

For example, if our package internal/todo contains an id parsing function, then a snippet for the README could be like this:

package main

import (
	"fmt"
	"strconv"
)

func parseID(s string) (int, error) {
	id, err := strconv.Atoi(s)
	if err != nil || id <= 0 {
		return 0, fmt.Errorf("id must be a positive integer")
	}
	return id, nil
}

Yes, this is a small fragment. And that’s its strength: the reader understands the contract in 10 seconds. In a README, such pieces work better than “here is the whole service end-to-end.” Let the full code live in the repository, and let the README show “how to think correctly” when using the project.

If you document a CLI utility (and our Tasky is exactly that), command examples are also part of the interface. And here it’s useful to capture not only the “happy path,” but also one typical error:

> done abc
error: id must be a positive integer

It looks like a small thing, but in practice it saves a ton of time. The person doesn’t guess “why doesn’t it work”; they see the expected message and adjust the input.

6. The “Architecture” section

Architecture in a README should not be a “full description of internals.” Its task is simpler: give the reader a map to quickly find the right place in the code. Especially when the project is no longer a single main.go file, but several packages, and someone has already “organized things” there (in a good sense, of course).

The “layers and data flow” approach works great here. Even if everything is simple so far, it helps you get used to discipline. For Tasky, the architecture can be described like this: cmd/tasky is responsible only for input/output, and the todo package is responsible for business logic around tasks. This matches the separation-of-responsibilities idea we’ve already seen: the UI/CLI layer should not smear domain logic across command handlers.

An example of a structural “map” right in the README could be:

cmd/tasky/           — entry point (main), command read loop
internal/todo/       — task domain logic (add, list, done)

Even better is a small diagram. For example, like this (Mermaid):

flowchart LR
    A[User] --> B[cmd/tasky: read command]
    B --> C[internal/todo: execute action]
    C --> B
    B --> D[stdout: print result]

Notice we don’t discuss storage details or networking—we need to show direction: where input is, where logic is, where output is. By the way, this style of “high-level system description” is found in real Go projects too: documentation can describe major components (frontend/worker/database and dependencies) without diving into the code of every file.

7. Architecture via a “project tree”

A project tree in a README is sometimes considered “too simple” or “childish.” In reality, it does one thing very well: it reduces anxiety. A beginner opens a repository, sees dozens of folders, and the brain starts suspecting that it will have to read the entire Internet. The tree lowers that panic: “here’s the entry, here’s the logic, here are the tests.”

For Tasky, the tree can look like this (and yes, this is a normal part of a README):

tasky/
  cmd/
    tasky/
      main.go          — console interface
  internal/
    todo/
      task.go          — Task model
      service.go       — Add/List/Done operations
  README.md
  go.mod

After the tree, it’s useful to give two or three sentences on how to “walk” the code. For example: “If you want to understand commands, start with cmd/tasky/main.go. If you want to change task title validation rules, look at internal/todo/service.go.” It sounds banal, but this is exactly the bridge that helps a person become productive quickly.

It’s important not to turn the tree into accounting. You don’t need to list every file if there are many. README should provide orientation, not turn into “ls -R.md”.

8. The “Constraints and guarantees” section

This section has a superpower: it prevents incorrect expectations. And incorrect expectations are the shortest path to bug reports like “nothing works,” when in fact “it works, you just thought it did something else.”

For Tasky, honest constraints right now could be: tasks are stored in memory and disappear after exit, commands are sensitive to input format, identifiers are positive integers. This can be described in 5–6 lines of text, without pathos.

For example, a README snippet:

## Constraints

Tasky stores tasks only in process memory. After the program finishes, the task list is cleared.

A task ID is a positive integer. The `done` command returns an error if the id is invalid or if there is no such task.

The word “guarantees” is also important. If you guarantee that done does not change other tasks, or that list prints tasks in insertion order, you can specify that. But specify only what you are truly ready to support. README is a promise. Don’t promise a “stable API forever” if tomorrow you’ll rename half the packages.

9. README and “consistency with the code”

The most common fate of a README is to become outdated. And not because you’re a bad person, but because the code changes every day, and the text is “sometime later.” That’s why reading a README is sometimes more painful than reading someone else’s code. And that’s a shame, because README was intended for the opposite.

There are several very down-to-earth rules that help a README stay alive. First, keep examples short: a short example is easier to update. Second, don’t write in the README what the code does not guarantee. Third, keep the quickstart as close to reality as possible: if you actually run the project via go run ./cmd/tasky, then write that, not “download the binary” that doesn’t exist.

Another useful technique is “a single source of truth” for terms. If you name an entity Task, don’t switch in the README to “todo-item,” “tasklet,” and “ticket” all at once. Otherwise the reader will decide those are different things.

And yes, README is also part of the interface, so treat it the same way as public functions: a bit less imagination, a bit more contracts.

10. An example of a “good README” for our Tasky

Below is an example skeleton of a README. It’s not perfect and not universal, but it shows “meaning density”: little text—lots of useful information. If you take this template, replace names and commands for your project, you’ll already get a readable document.

````md
# Tasky

Tasky is an educational console utility for managing a task list (todo).
Suitable as an example Go project with separation between CLI and business logic.

## Quickstart

Requirements: Go 1.25+

```bash
go run ./cmd/tasky

## Usage

Example commands:

```text
add Buy milk
list
done 1
```

## Architecture

`cmd/tasky` — console input/output and command parsing.
`internal/todo` — operations on tasks (Add/List/Done), input validation.

## Constraints

Data is stored only in process memory and disappears after exit.

This README does not try to be an encyclopedia, but it does the job of an interface: it provides meaning, a quick start, a usage scenario, code navigation landmarks, and behavioral boundaries.
````

11. Common mistakes when writing a README

Mistake #1: README starts with an “inspiring story,” not with what the project does.
Sometimes the first page turns into an essay: “we believe tasks should be happy.” That’s cute, but the reader first needs to understand the project’s purpose. First 1–2 sentences of “what it is,” then everything else.

Mistake #2: Quickstart is turned into an installation quest.
If quickstart requires 10 steps, three configuration files, and a shamanic dance around environment variables, most people simply won’t try the project. Quickstart must be short: one or two commands and a clear expected result.

Mistake #3: Usage examples are either missing or too huge.
No examples forces the user to guess. Examples that are too large make them close the tab. Better: several short scenarios, where each demonstrates one idea and one entry point.

Mistake #4: The “Architecture” section is a retelling of files instead of a map.
Listing “we have folders A, B, C” is not enough. It’s more useful to explain responsibilities: where input/output is, where logic is, where models are. A short diagram or a project tree often helps better than any text.

Mistake #5: README promises what the code does not guarantee.
Phrases like “100% stable output format” or “never crashes” usually end in pain. README is a contract. Promise only what you’re ready to support, and don’t be afraid to write constraints—honesty makes a project stronger.