Как документировать то, чего о системе никто не знает?

#Что такое неизвестное

Неизвестное

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

Если проще Записанный вопрос о вашей же системе, на который пока никто не ответил, — с пометкой, почему это важно.

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

#«Не найдено» — это не «этого нет»

Одна фраза, которая меняет поведение всей технической картины.

Допустим, анализ не упоминает резервное копирование. Верными могут быть три совершенно разные вещи:

1. Резервного копирования нет.
2. Оно есть и настроено там, куда анализ не заглядывал.
3. Оно есть, анализ туда заглядывал, но не смог понять, что оно делает.

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

Поэтому отсутствие находки никогда не подаётся как отсутствие вещи. Там, где анализ не может что-то установить, он это говорит и уточняет, в какой из трёх ситуаций находится.

#Виды неизвестного

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

#Как оно выглядит

ВЫСОКИЙ  Что происходит с платежом, который провайдер так и не
         подтвердил?
         О чём      Сервис биллинга
         Причина    Не установлено — путь сверки не найден
         Важно      Деньги могут быть списаны без записи о них.

СРЕДНИЙ  Куда ночная выгрузка пишет свой файл?
         О чём      Ночная выгрузка
         Причина    Вне охвата — получатель настроен вне репозитория
         Важно      Никто не может сказать, кто каждую ночь получает
                    данные клиентов.

НИЗКИЙ   Значит ли ещё что-нибудь приставка «legacy» у четырёх
         модулей?
         О чём      Четыре модуля
         Причина    Нужен человек — это история, а не код
         Важно      Новая команда будет обходить их или переписывать
                    из-за одного слова.

#Почему владельцу это нужно

Звучит наоборот: вы платите за картину, а вам выдают список того, чего она не знает.

Три причины, в том порядке, в каком они обычно становятся очевидны.

1. Это самый короткий возможный список вопросов

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

2. Он говорит, насколько картине можно верить

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

3. Это то, что сокращается

   Закрытое неизвестное — видимый прогресс. За несколько анализов список превращается в запись о том, как понимание возвращается, — а это куда лучшая мера передачи, чем количество написанных страниц.

#Как неизвестное закрывается

Двумя способами, и оба записываются, а не применяются молча.

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

Бывает и обратное, и этого стоит ожидать: анализ может открыть новое неизвестное о части, которая раньше была понятна. Это не регресс инструмента. Обычно это значит, что система изменилась так, что прежнее утверждение перестало подтверждаться, — ровно о таком вы и хотели узнавать.

#Охват: вторая половина

Неизвестное говорит, что не удалось установить. Охват говорит, куда смотрели. Нужны оба, и именно второе делает сравнение двух анализов честным.

Каждый анализ записывает по каждой области, была ли она покрыта полностью, частично или не покрыта вовсе, — и что было исключено намеренно. Поэтому 1ADK умеет отличать «этот компонент удалили» от «этот анализ туда не заглядывал». Там, где охват лишь частичный, ничто не сообщается как удалённое, потому что этого нельзя утверждать.

История изменений целиком на этом держится. Без охвата любой узкий анализ выглядел бы как снос.

#Чего это не чинит