March 6, 2026

Сегодня утром открыл проект, который не трогал три недели, и потратил двадцать минут, чтобы вспомнить, где что лежит. Звук клавиатуры стучал раздражённо, пока я переключался между файлами. Решил, что пора навести порядок в документации раз и навсегда.

Начал с простого: создал папку docs/ в корне репозитория. Внутри — три файла: README.md для быстрого старта, ARCHITECTURE.md для структуры проекта и SETUP.md для инструкций по развёртыванию. Ключевой момент — каждый файл отвечает на один конкретный вопрос. README объясняет "что это", ARCHITECTURE — "как это устроено", SETUP — "как это запустить".

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

Вот мой простой чеклист для документации проекта:

• README.md: название, что делает, как установить, как запустить
• ARCHITECTURE.md: структура папок, ключевые модули, потоки данных
• SETUP.md: окружение, зависимости, переменные среды, распространённые проблемы
• CHANGELOG.md: что менялось и когда (опционально)

Типичная ошибка — писать документацию "для себя сегодняшнего". Через три месяца ты уже другой человек и не помнишь контекст. Пиши так, будто объясняешь новому разработчику в команде. Используй короткие предложения, конкретные команды, примеры вывода.

Коллега спросил вчера: "Как ты запускаешь тесты?" Я отправил ему ссылку на SETUP.md вместо того, чтобы объяснять в чате. Сэкономил десять минут и понял, что документация работает, когда ты можешь просто скинуть ссылку.

Твоя задача на сегодня: открой свой последний проект и создай хотя бы один файл — README.md или SETUP.md. Напиши в нём три вещи: что это, как установить, как запустить. Пять минут работы сэкономят тебе часы в будущем.

#инструкция #документация #разработка #продуктивность