Как описать легаси-систему, которую никто не понимает?

#Почему проекты по документированию здесь проваливаются

Четыре причины, и ни одна из них не в том, что люди ленивы.

1. Безграничный объём. Никто не может сказать, что значит «задокументировано» для системы, которой никто не понимает, — значит, нет состояния, в котором проект закончен.
2. Прогресса не видно. Двенадцать написанных страниц из неизвестного числа — не прогресс, о котором можно отчитаться, который можно защитить или почувствовать.
3. Пишется по памяти о системе, которой никто не помнит. Обычный метод — посадить человека и попросить записать, что он знает — не работает, когда ответ в том, что он не знает.
4. Оно устаревает прямо в процессе написания. Полугодовая работа над документацией описывает систему, которая за эти полгода изменилась, и связи между этими двумя фактами нет.

Общее здесь одно: метод предполагает знающего автора, а легаси-система по определению та, где такого нет.

#Разделение

Последняя строка и меняет ощущение от всего этого. Решения не ветшают: «мы пробовали X, и не вышло из-за Y» — истина навсегда. Факты о системе ветшают постоянно, и ровно поэтому их надо выводить, а не набирать.

#Как сделать это ограниченным

Одно изменение делает задачу подъёмной: перестаньте мерить страницы и начните мерить открытые вопросы.

1. Выведите картину и дайте ей произвести список дыр

   Анализ, который сообщает, что установить не удалось, даёт конечный список с приоритетами: одиннадцать вопросов, из которых важны четыре.

   Это и есть момент, когда безграничная тревога становится ограниченной задачей, — и в этом весь фокус.

2. Расставьте список по последствиям

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

3. Закрывайте по одному и записывайте, кто ответил

   На часть отвечает чтение конкретного файла. На часть — человек. На часть — консоль облака. Каждый закрытый вопрос — абзац с датой и именем.

4. Пересоберите после существенных изменений и сравните

   Половина с фактами обновляется сама. Новые вопросы появляются там, где система сдвинулась, — а это ровно то, о чём вы и хотите узнать.

Теперь о прогрессе можно отчитаться: «мы начинали с тридцати одного открытого вопроса; осталось девять, и четыре высокоприоритетных закрыты». Такой фразы проект по документированию произвести не может никогда.

#То немногое, что стоит написать

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

• Зачем эта часть, в бизнес-терминах, в двух предложениях.
• Что мы установили и как, с доказательством — файл, консоль, человек.
• Чего мы всё ещё не знаем и почему это не закрыто.
• С чем быть осторожнее и по какой конкретно причине.
• Что пробовали и не сработало, если кто-то помнит.
• У кого спрашивать, если кто-то остался.

НОЧНАЯ ВЫГРУЗКА                      просмотрено 2026-08-25 · М. Пискунов

Зачем      Отправляет партнёру вчерашние платежи в виде CSV.

Установлено
  Запускается в 02:00 из crontab на сервере приложения, а не из
  планировщика репозитория.   (доказательство: /etc/cron.d/export, сервер)
  Пишет по пути из EXPORT_DEST, который задан в окружении и
  отсутствует в репозитории.  (доказательство: app/Console/Export.php:31)

Не известно
  Кто получает файл. EXPORT_DEST резолвится в SFTP-хост, который
  никто в компании не опознаёт.                        ВЫСОКИЙ
  Замечает ли кто-нибудь, когда это падает.            СРЕДНИЙ

Осторожно
  Обработки ошибок нет. Сбой происходит молча, оповещения нет.
  Считайте, что когда-то это уже падало и никто не заметил.

Спросить
  Некого. Аккаунт завёл подрядчик в 2022 году.

#Где это держать

• Выведенная картина — там, где она выводится, и обновляется при изменениях системы. Не копией в вики, где она разойдётся со своим источником.
• Открытые вопросы — одним списком, видимым всем, где закрытые сохраняются, а не удаляются.
• Написанные страницы — в репозитории, рядом с кодом, обычными файлами. Тогда они переезжают вместе с кодом, попадают в ревью и переживают смену вики.

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

#Что идёт не так

#Чего это не покрывает