lenec ru

← все посты

Татьяна Котова Подписаться

README, который читают: структура, которая работает

16K

Открываешь репозиторий чужой библиотеки. Хочешь понять: что это, зачем, как поставить, как убедиться, что подходит. Скроллишь README — и видишь полотно из бейджей, длинное «about the project», философию автора и обещание «getting started in 5 minutes», под которым ещё двадцать экранов настройки. К моменту, когда находишь команду установки, ты уже посмотрел документацию у двух конкурентов.

README — это первый и часто единственный документ, который читают про твой проект. Из всей документации он получает 80% трафика и формирует решение «брать или нет». Но писать его как маркетинговую страницу — провал, как технический справочник — провал, как инструкцию по установке — тоже провал. Разберу структуру, которая работает для библиотек, инструментов и сервисов, и что туда не нужно класть.

Что человек реально хочет узнать из README

Открывая README впервые, читатель ищет ответы на четыре вопроса в этом порядке:

  1. Что это и для кого. Решает ли мою задачу.
  2. Как быстро попробовать. Скопировать-вставить и увидеть результат.
  3. Где документация подробнее. Если зацепило, куда идти дальше.
  4. Активный ли проект. Когда последний релиз, кто отвечает на issues.

Всё остальное — детали, история разработки, сравнения с конкурентами, философия, контрибутинг — нужно процентам пяти читателей. Их можно и нужно убирать ниже или в отдельные документы.

Структура, которая работает

Минимально рабочий каркас README для библиотеки или инструмента:

  1. Заголовок и одна строчка-описание.
  2. Бейджи (ограниченно, см. ниже).
  3. Что это, в 2-3 предложениях.
  4. Установка.
  5. Минимальный пример использования.
  6. Ссылка на полную документацию.
  7. Поддержка/совместимость (версии языка, рантайма).
  8. Лицензия.

Всё. Если этого хватает — не добавляй больше. Длинный README не делает проект серьёзнее, он делает его утомительным.

Заголовок и описание: первое впечатление

Было:

# SuperParser

Welcome to SuperParser! This project was started in 2022
when we noticed that existing parsers had limitations...

Стало:

# SuperParser

Fast streaming JSON parser for Node.js with zero dependencies.
Handles files larger than memory.

Описание — одна строка, отвечает на «что это и зачем». Не «welcome», не «this project is», не история. Если у проекта есть конкуренты — упомяни ключевое отличие сразу: «zero dependencies», «handles files larger than memory», «built on top of X». Это то, что человек ищет глазами, листая список.

Бейджи: меньше — лучше

Бейджи бывают полезные и декоративные. Полезные:

  • Версия в npm/pypi/crates — показывает, что проект релизится.
  • Статус CI — показывает, что main собирается.
  • Ссылка на документацию (если она не очевидна).

Декоративные, которые можно убрать без потерь: количество звёзд GitHub, количество форков, количество скачиваний, code coverage в процентах, рейтинг качества кода с непонятного сайта, бейдж «PRs welcome», бейдж «made with love». Это шум, через который читатель продирается к описанию.

Если бейджей больше пяти — стоп, ты делаешь визуальный спам. Оставь два-три самых важных.

Установка: одна команда

Установка должна быть в первом экране. Не в «Getting Started», не в «Installation Guide», а прямо в README. И — короткой:

npm install superparser

Если установка реально сложная (нужны системные зависимости, компилятор, отдельный конфиг) — короткой версии нет, но в README дай минимум для счастливого пути на Linux/macOS, а полный гайд вынеси в отдельный файл и сошлись.

Опасный антипаттерн — давать сразу пять способов установки (npm, yarn, pnpm, bun, docker, бинарник). Выбери один основной, остальные — в раскрывающемся блоке или ссылкой. Иначе читатель тратит время на выбор там, где выбор не нужен.

Минимальный пример: запускается без правок

После установки — пример. Первое правило: пример должен запускаться, если его скопировать целиком.

Было:

import { parse } from 'superparser'

const result = parse(myData)
console.log(result)

Что не так: myData непонятно где взять. Читатель копирует, видит ошибку, лезет искать — это потерянная минута и плохое впечатление.

Стало:

import { parse } from 'superparser'

const data = '{"users":[{"name":"Alice"},{"name":"Bob"}]}'
const result = parse(data, { path: 'users.*.name' })
console.log(result)
// => ['Alice', 'Bob']

Конкретный вход, конкретный вызов, ожидаемый вывод комментарием. Читатель копирует, запускает, получает результат, видит, что библиотека работает. Дальше — листает за подробностями.

Если у библиотеки несколько ключевых сценариев — покажи 2-3 примера, не больше. Пятнадцать примеров в README превращают его в reference, и тот, кто хотел «попробовать», уходит.

Ссылка на документацию

Когда у проекта есть полная документация на отдельном сайте — README обязан на неё сослаться явно, а не спрятать в подвал. Хорошее место — сразу после минимального примера:

## Documentation

Full docs at [superparser.dev](https://superparser.dev):
streaming API, transforms, performance tips.

Не «check our wiki», не «see /docs», а конкретная ссылка с подсказкой о содержимом. Читатель должен понять, идти ли по ссылке.

Совместимость и требования

То, чего часто не хватает: какие версии языка/рантайма поддерживаются. Это знание, которое экономит читателю установку и откат.

## Requirements

- Node.js 20+
- Works in browsers via ESM bundle
- TypeScript 5.0+ for type definitions

Один абзац, конкретные версии. Без него читатель ставит, получает SyntaxError на каком-то ??=, и идёт писать в issues.

Что в README не нужно класть

Содержимое, которое часто оказывается в README, но почти всегда лучше живёт где-то ещё:

  • Полный API reference. Перегружает страницу. Сгенерируй его в отдельный сайт через TypeDoc/MkDocs/что-то ещё.
  • История разработки и changelog. Положи в CHANGELOG.md, дай ссылку.
  • Roadmap. Отдельный документ или GitHub Project. В README — две строки про статус (alpha/beta/stable), не больше.
  • Контрибутинг гайд. Это CONTRIBUTING.md. В README — одна строка «contributions welcome, see CONTRIBUTING.md».
  • Code of Conduct. Аналогично — отдельный файл.
  • Сравнительные таблицы с конкурентами. Спорно, часто превращается в маркетинг. Если сравниваешь — на отдельной странице доков.
  • Длинная секция «Why we built this». Один абзац мотивации в самом верху достаточно. Полная история — в блоге.

README для приложения, а не библиотеки

Если репозиторий — это приложение или сервис, а не библиотека для подключения, акценты другие:

  1. Что делает сервис.
  2. Скриншот или короткое демо (gif, статичная картинка).
  3. Как запустить локально (docker-compose up, make run).
  4. Как настроить (переменные окружения, конфиг).
  5. Как задеплоить или ссылка на инструкции по деплою.
  6. Архитектура в общих чертах (схема или 5 строк текста).

Скриншот в первом экране — это для приложений с UI важнее, чем для библиотек. Человек хочет увидеть, что получит, а не читать про функции.

Технические мелочи

  • Все блоки кода — с указанием языка для подсветки. ```bash, ```typescript, не голые ```.
  • Якоря для крупных секций: GitHub автоматически делает их из заголовков, можно ссылаться внутри README.
  • Не используй HTML-таблицы для оглавления, если оглавление не критично — на мобильных это плохо рендерится. Markdown-список из 4-6 пунктов лучше.
  • Картинки кладите в репозиторий (./docs/screenshot.png), а не на внешние хостинги. Внешний хостинг через год отвалится.
  • Для длинных секций (полная установка, пример конфига) используй <details> — на GitHub оно нормально работает и сворачивается.

Чек-лист перед коммитом README

  • В первом экране есть: что это, как поставить, минимальный пример.
  • Описание проекта — одна строка, без «welcome» и истории.
  • Бейджей не больше 5, все полезные (версия, CI, доки).
  • Пример использования копируется и запускается без правок.
  • Указаны минимальные версии рантайма/языка.
  • Есть ссылка на полную документацию, если она существует отдельно.
  • Лицензия указана.
  • Длина README — два-три экрана прокрутки на десктопе. Если больше — режь.

Хороший README — это не тот, в который положили всё, а тот, из которого выкинули лишнее. Читатель приходит с конкретным вопросом, и за минуту получает ответ или решение идти дальше. Большинство «непонятных» библиотек на самом деле понятны — просто их README заставляет читать пять минут до места, где это становится ясно.

Комментарии 0

  • Будьте первым, кто оставит комментарий.

Войдите, чтобы оставить комментарий.