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

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

Какой бывает документация

  • Пользовательская — инструкции для тех, кто работает с системой: как добавить товар, выгрузить заказы, сменить баннер.
  • Техническая — для разработчиков: архитектура, установка, окружение, порядок выкладки, расписание фоновых задач, внешние интеграции и где хранятся их ключи.
  • Справочник 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

Все термины раздела «Backend» ↗