Документация в маленьком проекте: что писать, а что нет

Почему её не пишут

Два честных объяснения. Первое: кажется, что и так всё помнят. Второе: непонятно, что писать, поэтому пишут либо ничего, либо пересказ кода.

Оба заканчиваются одинаково. Через три месяца автор не помнит, почему тут сделано так, а новый участник тратит неделю на то, что объяснялось бы за двадцать минут.

Что писать точно

Как запустить. Первое и самое нужное. Что установить, какие настройки задать, какой командой поднять, как проверить, что работает.

Проверка качества: человек, который никогда не видел проект, по этому тексту запускается сам, без вопросов. Если не запускается — текст плохой.

Зачем это всё. Пять предложений: что за проект, для кого, какую задачу решает. Без этого читатель разбирается в коде, не понимая замысла.

Почему сделано именно так. Самая ценная часть и самая редкая. Не «используем такое-то хранилище», а «выбрали такое-то, потому что нужен поиск по тексту, а другое пробовали и не подошло из-за такого-то».

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

Чего не писать

Пересказ кода. «Функция считает сумму, принимает список и возвращает число». Это видно из кода, а при изменении кода такая запись сразу врёт.

Подробное описание каждого экрана. Устаревает быстрее всего.

Планы на будущее в документации. Для этого есть задачи. В документации планы висят годами и вводят в заблуждение.

Правило, которое стоит запомнить

Устаревшая документация хуже, чем её отсутствие. Когда её нет, человек идёт разбираться в код. Когда она есть и врёт, он доверяет ей и делает неправильно.

Отсюда практический вывод: пишите мало, но поддерживайте. Три страницы, которые верны, полезнее тридцати, из которых половина устарела.

Где держать

В самом репозитории, рядом с кодом. Главный файл в корне плюс папка с записями решений, если их набирается много.

Причина простая: документация в отдельном месте не обновляется. Когда она лежит рядом и правится тем же изменением, что и код, шанс сохранить её в живых заметно выше.

Запись решения: формат на десять строк

Полезная привычка — на каждое существенное решение заводить короткую запись:

• Что решили.
• Когда.
• Какая была задача.
• Что рассматривали ещё.
• Почему выбрали это.
• Чем придётся заплатить.

Десять строк, пять минут. Через год это самый ценный текст в проекте.

Минимум для проекта на двоих

Один файл в корне: что за проект, как запустить, как устроено в общих чертах, что решили и почему. Одна страница.

Обновлять — когда меняется запуск или принимается новое существенное решение. Не чаще.

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