Короткий ответ
#Разделение, которое работает
| Факты о системе | Решения и привычки | |
|---|---|---|
| Примеры | Компоненты, зависимости, эндпоинты, потоки данных, работа по расписанию | Почему такой дизайн, что отвергли, что ломается регулярно, что проверять после выкатки |
| Где живёт | В системе | В людях |
| Лучший метод | Вывести | Задать конкретные письменные вопросы |
| Цена вручную | Дни и недели, и всё равно неполно | Час, если вопросы хорошие |
| Можно проверить? | Да, если несёт ссылки на источник | Нет — это свидетельство |
| Окно | Открыто бессрочно | Закрывается, когда перестают отвечать |
Почти любая плохая передача делает это наоборот: тратит закрывающееся окно на колонку, которая остаётся открытой, и производит документ о системе вместо документа о решениях.
#Что выводить
Это свойства кода, и установить их может любой, у кого есть к нему доступ, в любой момент — в том числе когда все уже ушли:
- Компоненты, из которых состоит система, с читаемым назначением у каждого.
- Что от чего зависит и в какую сторону.
- Интерфейсы, которые она предоставляет и потребляет, и примерно что делает каждая операция.
- Данные, которые она хранит, и куда эти данные движутся.
- Что работает по расписанию.
- И то, чего никогда не бывает в рукописной документации, — явный список того, что установить не удалось.
Последний пункт и делает выведенную картину полезнее написанной именно для передачи. У рукописного документа есть дыры, и он не знает, где они. Выведенный превращает каждую дыру в вопрос, который можно задать уходящей команде, пока она ещё здесь.
#Что обязан написать человек
Шесть вещей, ни одну из которых никакой анализ никогда не восстановит, примерно по убыванию ценности:
-
Что вам было бы страшно отдать на изменение и почему
Самый ценный абзац в любом документе передачи. Он короткий, конкретный и невыводимый.
-
Что пробовали и бросили
Не даёт новой команде потратить квартал на переоткрытие того, что подход здесь не работает.
-
Что здесь стоит из-за ограничения, которого больше нет
Вторая половина: не даёт им сохранить то, что уже можно убрать, или убрать то, что несущее.
-
Что ломается регулярно и что вы с этим делаете
Эксплуатационный ранбук, написанный как то, что происходит на самом деле, а не как процедура.
-
Какие оповещения важны, а какие шум
Без этого новая команда либо игнорирует всё, либо расследует всё.
-
Что приходится делать руками и когда
Месячные и квартальные ручные шаги обнаруживают на третий месяц — по их отсутствию.
#Как прописать это в договоре
«Документация и передача знаний» невозможна к исполнению, потому что нет состояния мира, в котором она полна или не полна. Замените это результатами, у которых есть истинностное значение:
При расторжении Исполнитель передаёт:
1. Письменные ответы на список вопросов, предоставленный
Заказчиком не позднее чем за 15 рабочих дней до окончания
работ. Заказчик вправе задать до 25 вопросов.
2. Неделю показа, в течение которой принимающая команда
Заказчика самостоятельно: (а) поднимает систему локально по
письменной инструкции, (б) выкатывает изменение в продакшен,
(в) откатывает это изменение и (г) разворачивает бэкап во
временную среду. Исполнитель доступен для консультаций.
3. Список всего, что работает и не лежит в репозитории.
4. Список всех внешних сервисов, от которых зависит система, с
указанием владельца аккаунта по каждому.
Приёмка: работы считаются завершёнными, когда принимающая
команда (а) самостоятельно выкатила, (б) развернула бэкап и
(в) правильно и письменно ответила на десять вопросов о системе,
выбранных Заказчиком.Каждая строка здесь проверяема, и ни одна не требует, чтобы кто-то оценивал, «достаточно ли хорош» документ. Выигрывают обе стороны: исполнитель точно знает, чем работа заканчивается.
#Как выглядит документ, который читают
Если человек всё-таки что-то пишет, то читают это снова или нет по трём свойствам:
- Коротко. Шесть прочитанных абзацев выигрывают у шестидесяти непрочитанных страниц. Документ передачи, который никто не дочитывает, не стоит ничего.
- Ответы, а не разделы. Написано как ответы на конкретные вопросы, а не как документ с воображаемой структурой. Вопросы задают порядок, по которому сможет двигаться кто-то другой.
- С датой и авторством. Утверждение о системе без даты и имени невозможно взвесить тому, кто найдёт его через два года.
#Что идёт не так
Просить «полную документацию системы».
Вместо этого Задайте двадцать пять конкретных вопросов. Безграничные просьбы порождают безграничную тревогу и документ, написанный так, чтобы выглядеть полным.
Заставить уходящую команду писать обзор архитектуры.
Вместо этого Выведите его. Их оставшиеся часы — единственный в мире источник для другой колонки.
Принять записанный видеообзор как результат.
Вместо этого Лучше, чем ничего, и хуже письменных ответов: два часа никто не пересматривает, искать по ним нельзя, а того, кому это нужно, ещё не наняли.
Написать один раз и не поставить дату.
Вместо этого Ставьте дату и авторство на каждой части. Документ передачи читают спустя годы люди, которым нужно понять, насколько ему доверять.
Производить документацию, которую нельзя проверить.
Вместо этого Где утверждение — факт о системе, оно должно указывать, откуда взялось. Где это свидетельство — должно быть сказано, чьё.
#Чего это не покрывает
Чего это не делает
- Продуктовую документацию для пользователей. Другая аудитория, другая задача.
- Документацию API для внешних потребителей: это публикуемый артефакт, а не артефакт передачи.
- Документацию для соответствия требованиям: у неё есть заданная форма, которую определяет кто-то другой.
- Вопрос о том, кто всё это потом поддерживает, — вопрос настоящий, и именно поэтому со временем выведенная картина стоит дороже написанной.