§4.03 Документация системы (артефакты)
Время: 60 мин чтение + 40 мин = 100 мин Что узнаешь: почему документация — это не описание и не сама система, а физический артефакт, в котором зафиксировано описание, и как понимание этого улучшает работу с любыми документами
В одном предложении: документация системы — это физический артефакт, в котором зафиксировано описание системы, мост между ментальными моделями разных людей; документация может устаревать независимо от того, как изменились воплощение и описание.
Сигнатура понятий:
- Документация системы — это физический артефакт (файл, документ, схема, запись), в котором зафиксировано описание системы или её части; существует в физическом мире, может быть передана, скопирована, уничтожена
Мем, который снимается. «Описание и документация - одно и то же, только одно в голове, другое на бумаге.» На самом деле это разные объекты с разными свойствами. Описание существует только в момент, когда кто-то думает о системе; оно гибко и меняется мгновенно. Документация - физический объект: файл на диске, страница в вики, схема в Miro. Она существует независимо от того, думает ли кто-нибудь о ней прямо сейчас. И, что важно, она может стать неактуальной: система изменилась, описание обновилось, а документация осталась прежней. Путаница между описанием и документацией - источник работы с устаревшими данными.
Определение из источника.
В Pack (PD.FORM.027) документация системы определена как артефакт описания системы - физически существующий объект, фиксирующий некоторое описание системы в определённый момент времени. Документация имеет физические свойства воплощения (занимает место на диске, в архиве, в памяти браузера) и информационные свойства описания (содержит модель системы).
Принципиальная характеристика документации: она фиксирована во времени. В момент создания документация соответствует описанию. После этого воплощение может измениться, описание - обновиться, а документация остаётся прежней, пока её явно не обновят. Это создаёт риск расхождения: документация описывает систему, которой больше нет.
Хорошая документация - не самоцель, а рабочий инструмент. Документ полезен ровно настолько, насколько он помогает нужным людям в нужный момент понять систему правильно.
Развитие мысли.
Документация занимает особое место в тройном различении: она одновременно физична (как воплощение) и содержит описание (как ментальная модель). Это делает её мостом - способом передавать описания между людьми, которые не могут напрямую обменяться ментальными моделями.
Без документации синхронизация описаний требует живой коммуникации. Когда в команде пять человек, это ещё возможно. Когда сто - уже нет. Документация масштабирует передачу описаний: одна схема архитектуры может синхронизировать описание системы у всей команды, не требуя ста персональных разговоров.
Но документация имеет цену. Каждый документ нужно создать и поддерживать актуальным. Устаревший документ хуже отсутствующего: он даёт ложное чувство осведомлённости и вводит в заблуждение. Поэтому у документации должен быть явный «владелец описания» - кто-то, кто отвечает за соответствие документации реальному воплощению и актуальному описанию.
Для созидателя документация собственного развития — это Pack, дневники рефлексии, записи в IWE. Их ценность не в объёме, а в том, насколько они отражают актуальное описание. Система, в которой есть воплощение (практики, инструменты) и описание (ментальная модель своего развития), но нет документации, - хрупкая: всё в голове, и при изменении контекста теряется.
Метод - минимальный шаг. Практика «Аудит одного документа» (40 мин):
- Выберите один документ, которым вы регулярно пользуетесь: инструкцию, схему процесса, описание продукта (5 мин).
- Ответьте на вопрос: «Какое описание какой системы зафиксировано в этом документе?» Запишите одним предложением (10 мин).
- Ответьте на вопрос: «Насколько актуален этот документ?» Когда последний раз обновлялся? Изменилась ли система с тех пор? (10 мин).
- Если документ устарел: запишите, что именно в нём не соответствует актуальному воплощению или описанию системы. Нужно ли его обновить или удалить? (15 мин).
Пример из жизни. Игорь - технический руководитель, обнаружил, что его команда тратит несколько часов в неделю на онбординг новых разработчиков по документации, которая была написана два года назад. За это время стек поменялся, архитектура изменилась, процессы обновились. Документация описывала систему, которой больше не существовало, но продолжала существовать как физический артефакт. Новые сотрудники учились по устаревшей документации и потом с удивлением обнаруживали, что реальная система работает иначе. Когда Игорь прояснил тройное различение для команды, они договорились: документация должна быть «живой» - её актуальность проверяется каждые три месяца. Объём документации сократился, а качество онбординга выросло.
Типичная ошибка. «Чем больше документации, тем лучше.» На самом деле документация полезна только тогда, когда кто-то её читает и доверяет ей. Большой объём устаревшей документации создаёт «шум»: непонятно, чему верить. Документация «для отчёта» (чтобы было) - не документация, а имитация. Это заметно по следующему признаку: если документ никто не читает и он никогда не влияет на решения, он не выполняет функцию документации.
Вторая ошибка: считать, что нет документации - нет системы. Воплощение существует независимо от документации. Команда работает, даже если не задокументирован процесс. Продукт функционирует, даже если нет актуальной архитектурной схемы. Отсутствие документации — это риск синхронизации, не отсутствие системы.
Степени мастерства:
| Степень | Что происходит | Критерий перехода |
|---|---|---|
| 1. Объясняю | Могу объяснить, что документация — это физический артефакт, фиксирующий описание, и привести пример устаревшей документации | Один раз выполнил практику «Аудит одного документа» |
| 2. Умею | Могу для любого документа сказать, что именно он описывает и насколько это актуально | Есть запись: документ + что описывает + актуальность |
| 3. Навык | При работе с документацией автоматически проверяю её актуальность перед использованием | Регулярность: каждый используемый документ проверяется на соответствие воплощению |
| 4. Мастерство | Помогаю командам выстроить систему поддержания актуальности документации | Есть кейс, где аудит документации улучшил работу команды |
Проверка себя.
- Понимание: вы можете объяснить, почему документация может быть «ложью» - не потому что кто-то солгал, а потому что воплощение изменилось после её создания.
- Поведение: перед использованием важного документа вы проверяете: когда он последний раз обновлялся и изменялась ли система с тех пор.
- Застревание: если вы не можете назвать, чьё описание какой системы зафиксировано в документе, документ, вероятно, слабо связан с конкретным воплощением. Спросите: «Для кого и о чём этот документ?»
Что дальше. Теперь все три уровня введены: воплощение, описание, документация. Они существуют одновременно для любой системы. Следующий подраздел - о тройном различении на практике: как применять его к реальным ситуациям и что происходит, когда уровни путают.