Короткий ответ
#Почему это лучше неверной документации
Ощущается иначе, поэтому стоит сказать конкретно.
Система с уверенным устаревшим архитектурным документом стоит вам той же работы по выяснению плюс время, потраченное на доверие к нему, плюс решения, принятые на его основании, плюс момент, когда кто-то находит расхождение и теперь не доверяет и всему остальному в нём.
Система, где нет ничего, стоит вам работы по выяснению — и больше ничего. Вы стартуете из верной модели собственного знания, а именно: его нет. Это на удивление чистое место для начала.
С чем стоит быть осторожным
«Документации нет» часто оказывается «документации, о которой кто-то упомянул, нет». README от 2021 года, вики, которую никто не открывал, комментарии в шапках трёх файлов, письмо про онбординг в чьём-то архиве. Найдите их — а потом относитесь к каждому как к заявлению, которое надо проверить, а не как к факту.
#Первая неделя
-
День первый — что запущено и на чьих аккаунтах
Какие есть среды, что в каждой развёрнуто и по каждому нужному системе аккаунту: на чью личность оформлен, кому выставляют счёт, куда ведут контакты восстановления.
Проблемы владения дешевле всего поднимать на первой неделе и дороже всего обнаруживать на восьмом месяце. Сделайте это до всего технического.
-
День первый — возьмите независимую копию данных
Бэкап, который держите вы, в месте, которым не управляет никто другой, и который вы лично открывали. Всё остальное из этого списка можно повторить позже; это то, что защищает вас в наихудшем случае.
-
День второй — выведите опись
Компоненты, зависимости, интерфейсы, потоки данных, что работает по расписанию. Произвести это может любой, кто способен выкачать репозиторий; человек, понимающий систему, для этого не нужен — и это к счастью.
-
День третий — внешние границы
Внешние сервисы, в которые она ходит, интерфейсы, которые она предоставляет, и кто вне компании может на них опираться. Сверьте технический список со счетами: то, что есть в одном и нет в другом, — это вопрос.
-
День четвёртый — запишите, на что никто не может ответить
С приоритетами и причинами. Этот список и есть результат недели. Он превращает «мы не понимаем собственную систему» в одиннадцать конкретных вопросов, из которых важны четыре.
-
День пятый — докажите, что можете это эксплуатировать
Поднимите локально. Выкатите что-нибудь пустяковое. Разверните взятый в первый день бэкап во временную среду. Каждое из этого либо работает, либо даёт вам что-то конкретное для починки.
#Что читать вместо документации
Система без документации всё равно полна свидетельств о себе самой.
| Источник | Что он сообщает |
|---|---|
| История коммитов | Какие файлы меняются вместе, какие области нестабильны, кто над чем работал, а иногда и почему |
| Пул-реквесты и задачи | Рассуждения, которые так и не попали ни в один документ. Часто самый богатый источник |
| Тесты | Намерение. Там, где они расходятся с кодом, произошло что-то интересное |
| Счета | Грубую карту внешних зависимостей — с совершенно независимой стороны |
| Консоль облака | Всё, что существует и чего нет в репозитории |
| Трекер ошибок | Что ломается на самом деле, как часто и в каком компоненте |
| Тикеты поддержки | Что делают пользователи из того, что система обрабатывает плохо. Взгляд, которого нет ни у одного инженера |
| Логи выкаток | Кто выкатывал, как часто и делал ли это когда-нибудь кто-то, кроме одного человека |
Первые два стабильно недооценивают. Четырёхлетняя история коммитов и пара сотен пул-реквестов содержат существенную часть тех рассуждений, которые проект по документированию попытался бы восстановить по памяти.
#Как найти хоть кого-то знающего
«Спросить некого» часто означает «некого очевидного». Стоит попробовать в таком порядке:
- История коммитов. Кто писал рискованные части? До кого из них можно достучаться? Двадцатиминутный звонок тому, кто ушёл два года назад, может стоить недели.
- Поддержка и эксплуатация. Люди, годами разбиравшие тикеты по этой системе, знают то, чего не записал ни один инженер.
- Финансист. Он знает, каким поставщикам платят, а это самый надёжный список внешних зависимостей в компании.
- Сами поставщики. Платёжный провайдер или хостинг могут сказать, какой аккаунт существует и кто его заводил.
- Давно работающие нетехнические сотрудники. Они знают, что система делала раньше, что сломалось в прошлом году и что все обходят стороной.
#Что записывать и куда
Способ провалить всё это упражнение — оставить понимание в голове одного нового человека: это исходная проблема с новым именем.
Три вещи, которые стоит хранить, и они небольшие:
- Опись и зависимости, выведенные, а не набранные, и обновляемые, когда меняется что-то существенное.
- Список открытых вопросов, который сокращается, с ответом и именем ответившего рядом с каждым закрытым.
- Короткий файл решений — по абзацу каждый раз, когда кто-то установил что-то неочевидное. С датой, авторством, в репозитории.
#Что идёт не так
Начать с чтения кода.
Вместо этого Начните с того, что запущено, на чьих аккаунтах и с независимой копии данных. Ничто из этого не требует что-либо понимать.
Написать недостающую документацию.
Вместо этого Структурную половину выведите; пишите только решения, по мере того как их устанавливаете. Проект по документированию здесь безграничен и не закончится.
Чинить то, что попадается по дороге.
Вместо этого Запишите и идите дальше. Менять систему, которой не понимаешь, — это то, как неделя выяснения превращается в неделю инцидентов.
Держать всё в собственной голове.
Вместо этого Всё уходит туда, где это прочитает компания. Иначе новой точкой отказа стали вы.
Считать, что никто ничего не знает.
Вместо этого Прежде чем делать такой вывод, проверьте историю коммитов, поддержку и счета. Почти всегда кто-нибудь есть.
#Чего это не покрывает
Чего это не делает
- Решение, оставить систему, переписать её или заменить. Сначала проведите неделю; после неё решение выглядит иначе.
- Найм. Нужен ли вам под это постоянный человек — отдельный вопрос.
- Ревью безопасности. Установление того, из чего состоит система, — вход для него, а не замена.
- Всё, что касается коммерческого и юридического положения, доставшегося вам вместе с программой.