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