04Документация

Структура README

Что и в каком порядке должно быть в README — чтобы новый человек запустил проект за 5 минут.

Напиши / улучши README для {{project}}.

Структура (в этом порядке)

# Имя проекта

[Одна строка: что это и зачем]

[Опционально: ссылки/бейджи — build, version, license]

## Что внутри

Краткое описание проблемы и решения. 2-3 абзаца **с примером**.

## Быстрый старт

```bash
git clone ...
cd project
npm install
npm run dev

Если работает — ты увидишь X на http://localhost:3000.

Использование

import { thing } from 'project';

const result = thing({ ... });

2-3 типичных примера.

Конфигурация

Переменная	Значение	Описание
FOO	required	...
BAR	optional, default=baz	...

Документация

Разработка

npm install
npm run dev
npm test
npm run build

Требования: Node 20+, etc.

Вклад

Смотри CONTRIBUTING.md.

Лицензия

MIT (см. LICENSE)


## Принципы

## 1. Самый ценный — первый экран
Решение, что внутри, как запустить — должно быть в первых 30 строках. Не клади в начало "благодарности" и историю проекта.

## 2. Покажи код
Один работающий пример лучше 1000 слов описания.

## 3. Quick start — реально quick
- Команд минимум
- Без "сначала установите 5 зависимостей"
- Финальный шаг — что-то видно (URL, console output)

## 4. Документируй секреты явно
- Что нужно в `.env`
- Где взять API ключи
- Какие права нужны

## 5. Учитывай аудитории
- Пользователь библиотеки → как использовать
- Контрибьютор → как разработать
- Менеджер / любопытный → что это вообще
- Поисковый — что нужно сделать
- Должны быть разделены

## 6. Бейджи — функциональные, не декоративные
- Build status — да
- Coverage — да
- Version — да
- "Made with ❤️" — нет

## 7. Скриншоты / гифки
Особенно для UI-проектов. Одна гифка экономит абзац описания.

## Анти-паттерны

- ❌ Длинная история ("я создал это в 2020...")
- ❌ Установка которая занимает 5 шагов и не работает
- ❌ Примеры с `foo` / `bar` вместо реалистичных данных
- ❌ Устаревший README — версия в нём не совпадает с package.json
- ❌ TODO в README — нет, починить или удалить
- ❌ Отсутствие лицензии

**Тест: возьми junior-разработчика. Дай ему README. Может ли он запустить за 5 минут без вопросов?**

## В конце
- Готовый README (markdown)
- Список того что ещё надо документировать в отдельных файлах