Как писать техдокументацию, чтобы через год всё ещё понимать

Коротко о главном#

Документация, которая переживает полгода, отвечает на четыре вопроса без поиска в чатах и логах:

• зачем это сделано;
• как это запущено;
• как проверить, что оно работает;
• как откатиться или починить, если сломалось.

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

Почему документация умирает#

Документация умирает не потому, что никто не пишет. Обычно её убивают пять типичных ошибок:

1. Пишут для себя в моменте. Автор помнит контекст, читатель через год - нет.
2. Описывают команды, но не результат. Команда без ожидаемого вывода бесполезна.
3. Нет отката. Без rollback шага документ описывает только happy path.
4. Нет проверок. «Работает на моей машине» - это не проверка.
5. Нет ответственного. Если непонятно, кто обновляет документ, он не обновляется.

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

Что гарантирует полезность документа#

Четыре признака повышают шанс, что документ выживет:

• Он короткий. Чем меньше текста, тем больше шанс, что его прочитают.
• Он привязан к коду. Команды копируются из документа и запускаются.
• Он содержит проверочные шаги. «curl вернул 200» лучше, чем «сайт поднялся».
• Он обновляется вместе с изменением. Документ обновляют вместе с патчем, а не отдельной задачей.

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

Железные правила#

ssh user@server
docker compose up

ssh deploy@203.0.113.10
cd /opt/app
docker compose up -d
docker compose ps

curl -I https://example.com

Шаблон хорошего runbook#

# Название задачи

Дата: 2026-10-14
Автор: ansible

## Цель

Что мы делаем и какой результат ожидаем.

## Контекст

- где находится система;
- какие ограничения;
- что уже настроено;
- какие доступы нужны.

## Предусловия

- root/ssh;
- backup сделан;
- домен указывает на IP.

## Шаги

1. Сделать backup.
2. Применить изменение.
3. Проверить.

## Проверка

- команда 1;
- команда 2;
- ожидаемый вывод.

## Откат

- шаг 1;
- шаг 2;
- проверка отката.

## Чек-лист

- [ ] backup есть
- [ ] тесты прошли
- [ ] логи чисты

## Ссылки

- репозиторий;
- dashboard;
- backup job.

Шаблон работает, если держать его коротким и конкретным.

Таблица: типы документации#

README должен отвечать на вопрос «как запустить». Runbook - «как применить на проде». ADR - «почему так сделали».

Пример плохого и хорошего документа#

Плохой:

## Деплой

Запусти compose. Загрузи образ. Проверь.

Читатель не знает, какой compose, куда загрузить, как проверить.

Хороший:

## Деплой релиза 1.4.0

Дата: 2026-10-14
Сервер: app-01

### 1. Сделать backup базы

```bash
pg_dump -Fc production > /backup/db-$(date +%F).dump

Ожидается файл размером более 100 МБ.

2. Обновить код#

cd /opt/app
git fetch --tags
git checkout v1.4.0

3. Перезапустить#

docker compose up -d
docker compose ps

Ожидается: все контейнеры в статусе running.

Откат#

git checkout v1.3.9
docker compose up -d

Это длиннее, но читается за минуту и не требует догадок.

### Как выбирать уровень деталей

Не каждое действие нужно расписывать. Используйте три уровня детализации:

- **Уровень 0**: очевидно. Не пишите «как открыть терминал».
- **Уровень 1**: стандартная задача. Пишите шаги без лишних пояснений.
- **Уровень 2**: рискованная операция. Пишите проверки, откат и ожидания.

Если документ всё время повторяет стандартные действия, вырастает шум. Если не покрывает рискованные шаги, он опасен.

### Конкретные приёмы, которые работают

#### Думайте о будущем читателе

Перед публикацией задайте себе вопросы:

- что этот документ решает;
- какие команды реально запустятся;
- где чаще всего ломаются;
- что нужно проверить руками;
- что будет, если шаг пропустить.

Если ответ на любой вопрос неясен, текст незавершён.

#### Пишите решения, а не уроки

Обучающий материал требует контекста, исключений и «почему». Операционный документ требует «что сделать», «как проверить» и «как откатить». Не смешивайте.

#### Держите единый стиль команд

Используйте единообразно:

- регистр;
- отступы;
- имена;
- формат дат.

Если в одном документе встречаются и `docker-compose`, и `docker compose`, это мелочь, но она размывает стиль.

#### Делайте снимки системных состояний

Храните:

- docker compose ps;
- systemctl status;
- uname -a;
- версию приложения;
- checksum конфига.

Так инцидент разбирать легче.

#### Пишите маленькие коммиты

Лучше 3 документа по 2 страницы, чем один гигант на 30. Гигант читается целиком только один раз - в день написания.

### Чек-лист перед коммитом документа

Проверьте:

- [ ] заголовок ясный;
- [ ] цель указана;
- [ ] шаги пронумерованы;
- [ ] команды копируются;
- [ ] есть expected result;
- [ ] есть rollback;
- [ ] есть проверка;
- [ ] дата актуальна;
- [ ] нет абстрактных «настроить как следует»;
- [ ] есть ссылки на код/дашборд;
- [ ] документ можно удалить без потери знания, если проект удалён.

Если не отмечено хотя бы два пункта, документ не готов к пушу.

### Инструменты и процесс

Полезные привычки:

- хранить docs в том же репозитории, что код;
- привязывать изменение документа к патчу;
- использовать review, как для кода;
- хранить шаблоны runbook в `docs/templates/`;
- проверять команды на чистом окружении;
- добавлять CLI-smoke tests для инструкций;
- использовать `docs/` как источник истины, а wiki - как дополение.

Wiki удобна, но быстро рассыпается. Если код и документ живут в одном репозитории, их проще синхронизировать.

### Шаблон коммита для документации

```text
docs(runbook): update deploy steps for v1.4.0

- added pre-backup
- added rollback
- fixed service name

Так коммит сразу рассказывает, зачем изменён документ.

Частые вопросы#

Нужно ли вообще писать документацию, если есть код? Код показывает, как что-то работает, но не объясняет, зачем, как запустить и как откатить. Без небольшой документации почти всегда придётся разбираться заново.

Сколько должен быть документ? Коротко, но достаточно полно. Лучше один runbook на 2 страницы, чем гигант на 30.

Что важнее: подробность или краткость? Для операционных задач важны краткость и проверки. Для архитектуры - краткость, границы и причины.

Как понять, что документ устарел? Если при запуске хотя бы одна команда не работает или ожидаемый вывод изменился, документ устарел.

Можно ли один документ для всех? Нет. У разных читателей разные цели. README - для нового разработчика, runbook - для on-call, ADR - для архитектора.

Выводы#

Хорошая техдокументация - надёжный чек-лист. Она сохраняет знание, не заменяя его. Если документ содержит цель, шаги, проверку и откат, он помогает через год. Без них - только в первый день.

Минимум, который стоит записать:

1. Цель.
2. Предусловия.
3. Шаги.
4. Проверка.
5. Откат.
6. Дата и автор.

NOTE

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

TIP

Лучший способ понять ценность docs - убрать себя из процесса запуска и посмотреть, где читатель застрянет.