Что такое «Документация»
Код показывает, что делает система, но не объясняет, зачем она так устроена, как её развернуть и что сломается, если поменять настройку. Эти ответы хранит документация. Без неё знание живёт в голове одного разработчика и уходит вместе с ним — частая история, когда сайт переходит на поддержку к новому подрядчику.
Какой бывает документация
- Пользовательская — инструкции для тех, кто работает с системой: как добавить товар, выгрузить заказы, сменить баннер.
- Техническая — для разработчиков: архитектура, установка, окружение, порядок выкладки, расписание фоновых задач, внешние интеграции и где хранятся их ключи.
- Справочник API — список методов, параметров и ответов. Его часто описывают в машиночитаемых форматах вроде OpenAPI или RAML и генерируют из них страницу документации.
- Проектная — техническое задание, схемы, принятые архитектурные решения. Как устроено техническое задание на разработку сайта, разобрано отдельно.
Отдельный уровень — пояснения прямо в коде. Комментарии и блоки PHPDoc описывают конкретную функцию, а документация — систему целиком.
Пример: README для сайта на поддержке
Сайт компании «Пример»
Окружение: PHP 8.3, MariaDB 11, nginx, Redis для объектного кэша
Запуск: docker compose up -d, затем импорт дампа из /backup
Выкладка: git pull на сервере, после — сброс OPcache и кэша сайта
Интеграции: обмен с 1С каждые 15 минут
Секреты: ключи и пароли — в .env, не в репозитории
Такой файл на полстраницы экономит новому разработчику дни на разбор проекта и снижает риск уронить сайт при первой же выкладке.
Как не дать документации устареть
Устаревшая инструкция опаснее отсутствующей: ей доверяют. Помогает подход «документация как код»: тексты лежат в том же репозитории, что и программа, и правятся в том же коммите, что и поведение. Справочник API лучше генерировать из кода или спецификации, а не вести вручную. И писать стоит для конкретного читателя: менеджеру не нужна схема базы, а разработчику — скриншоты админки.
Связанные термины
Обновлено: 10 октября 2026

