Почему документация устаревает быстрее кода — и как мы поймали это числом

Код проверяют тесты. Документацию не проверяет никто — и она расходится с реальностью молча, в одну сторону: не там, где написано лишнее, а там, где написанное перестало быть правдой.

Мы решили измерить, насколько.

Что показала сверка

Одна сверка планов с кодом нашла 14 задач, закрытых в коде и числящихся открытыми.

Расхождение шло в неожиданную сторону. Обычно боятся обратного — «в плане закрыто, а в коде нет». На практике чаще встречается «сделано и не отмечено», и стоит оно дороже: по такому плану человек либо не делает работу, которая уже сделана, либо делает её второй раз.

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

Почему отметка не ставится сама

Отметку ставит человек в конце работы, когда внимание уже ушло на следующее. Это не небрежность, это устройство внимания: задача закрыта в голове раньше, чем закрыта в документе.

Значит, полагаться на дисциплину бесполезно. Нужно либо делать отметку частью того же изменения, что и код, либо не иметь плана вовсе.

Три правила, два из которых держит машина

1. У каждого плана в шапке — строка статуса с датой сверки. Не «в работе» вообще, а «в работе, сверено такого-то числа». План без даты не отличим от плана, который никто не открывал полгода.

2. Рядом с каждой отметкой «сделано» стоит, чем она проверяется — файл, миграция, номер решения, номер версии. Отметка без адреса не проверяется никем и через месяц становится враньём.

3. Отметка ставится тем же изменением, что и код. Не «потом одним заходом».

Первые два проверяет гейт в общем прогоне. И он честно говорит о своей границе: он проверяет форму, а не факт. Строка, где путь назван в описании задачи, пройдёт, даже если работа не сделана. Отличить упоминание от сделанного машина не может — это работа периодической сверки, и её результат ложится в отдельный документ.

Отдельно про «наполовину»

Сделано наполовину — это не «сделано». У нас для этого своя отметка и обязательная фраза, чего именно не хватает.

Половина, названная целым, дороже честного пробела: по пробелу принимают решение «надо сделать», а по ложному «готово» — «можно продавать».

Как проверить у себя

Возьмите свой план и три случайные строки со статусом «сделано». По каждой ответьте: чем это проверяется прямо сейчас?

Если ответ «я помню» — у вас та же история, просто вы её ещё не считали.

Что из этого следует

Документация проекта не устаревает от времени. Она устаревает от каждого изменения кода, которое её не тронуло, — то есть от почти каждого.

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

---

У нас документы проекта живут рядом с задачами и связаны с ними ссылками — чтобы вопрос «где мы это решили» имел ответ через полгода. Как это устроено — Документы.