🌀 Марианская впадина и выжженное поле документации 🌋
Иногда мне кажется, что мы прокляты или отсутствием документации, или ее избыточным количеством!
🌵 Первое проклятие: выжженное поле.
Это проекты без документации. Ты приходишь, вокруг пусто, торчат "бадылки" кода, а объяснений — nichts. Ты даже не знаешь, что когда-то должно было тут расти. Нет комментариев, нет задач. Это уже не археология, так как даже код устарел, и обращаться к нему, как к истине может быть ОПАСНО (как в анекдоте: ниточку оборвешь — уши отвалятся)!
🌊 Второе проклятие: Марианская впадина.
Это противоположность: документации так много, что ты просто теряешься. За одним конфлюенсом скрывается еще один, архивный. А за ним — целый лабиринт тикетов в JIRA, а проектов несколько и часть тоже архивная.
И что хуже — отсутствие документации или ее избыток?
На мой взгляд, избыточная документация пугает больше. Она демотивирует, создает апатию, потому что:
- Трудно объяснить, почему при ее обилии все равно не хватает информации.
- Трудно использовать неподдерживаемые документы, которые давно устарели.
- Это не помогает другим командам/новичкам/"археологам" понять, как проект устроен — они просто теряются в потоке.
Я не могу придумать красивое решение, как выйти из ситуации, когда вас "завалило" доками! ИМХО, путь тот же, что и с отсутвием - начать с чистого листа создавать документацию!
🎯 Но с учетом того, что важно помнить о нескольких условиях!
☝️ 0: Определите ЦЕЛЬ и ПОТРЕБИТЕЛЕЙ документации.
Без этого пункта можно ничего не писать! Так как получится, что либо написанное никому ненужно, либо для тех кому нужно так и не появилась документация!
1️⃣ Сначала договоритесь о терминах.
Никакой документации не будет толку, если внутри команды все понимают слова по-разному. На днях столкнулась с ситуацией, когда для меня "зонтик" = кросс-командный проект, для коллеги — кобренд с внешним партнером.
2️⃣ Определите продукт и его границы.
О чем ваш продукт? Кто его потребитель? Это не просто набор фич. Это должен быть четко очерченный набор ценностей, которые продукт приносит.
3️⃣ Поймите, как ваш продукт монетизируется.
Даже если он внутренний (например, платформа), его монетизация — это сокращение затрат других подразделений. Это тоже нужно учитывать.
4️⃣ Решите, нужна ли вам документация наружу.
Если у вас платформа (а уж если не платформа - тем более), подумайте, будете ли вы публиковать документацию (и какую ее часть) для внешних пользователей. Это определяет, как выстроить структуру документов.
5️⃣ Сосредоточьтесь на “бережливой документации”.
Не нужно писать многотомные руководства, которые никто не будет читать. Актуализируйте, если не постоянно, то — регулярно. Разделяйте информацию на уровне: стратегический (общее представление) и тактический (подробные инструкции).
6️⃣ Интегрируйте документацию в процесс работы.
Документация должна быть не только полезной, но и доступной, а также стать частью вашего рабочего процесса! Документы — это артефакты фиксации мыслей, и именно через них можно идеи челенджить, тестировать, да и риски митигировать и нивелировать на этапе документирования приятнее, чем в проде :)
Хорошая документация — это баланс между пустотой и хаосом. Это не только описание текущего состояния, но и инструмент, который помогает новым людям разобраться в проекте, а продукту — развиваться.
А как вы справляетесь с “проклятиями” документации? Какие аксиомы лежат в базисе ваших артефактов? Делитесь опытом, мне будет интересно! 😊
#architecture #project_management
Иногда мне кажется, что мы прокляты или отсутствием документации, или ее избыточным количеством!
🌵 Первое проклятие: выжженное поле.
Это проекты без документации. Ты приходишь, вокруг пусто, торчат "бадылки" кода, а объяснений — nichts. Ты даже не знаешь, что когда-то должно было тут расти. Нет комментариев, нет задач. Это уже не археология, так как даже код устарел, и обращаться к нему, как к истине может быть ОПАСНО (как в анекдоте: ниточку оборвешь — уши отвалятся)!
🌊 Второе проклятие: Марианская впадина.
Это противоположность: документации так много, что ты просто теряешься. За одним конфлюенсом скрывается еще один, архивный. А за ним — целый лабиринт тикетов в JIRA, а проектов несколько и часть тоже архивная.
И что хуже — отсутствие документации или ее избыток?
На мой взгляд, избыточная документация пугает больше. Она демотивирует, создает апатию, потому что:
- Трудно объяснить, почему при ее обилии все равно не хватает информации.
- Трудно использовать неподдерживаемые документы, которые давно устарели.
- Это не помогает другим командам/новичкам/"археологам" понять, как проект устроен — они просто теряются в потоке.
Я не могу придумать красивое решение, как выйти из ситуации, когда вас "завалило" доками! ИМХО, путь тот же, что и с отсутвием - начать с чистого листа создавать документацию!
🎯 Но с учетом того, что важно помнить о нескольких условиях!
☝️ 0: Определите ЦЕЛЬ и ПОТРЕБИТЕЛЕЙ документации.
Без этого пункта можно ничего не писать! Так как получится, что либо написанное никому ненужно, либо для тех кому нужно так и не появилась документация!
1️⃣ Сначала договоритесь о терминах.
Никакой документации не будет толку, если внутри команды все понимают слова по-разному. На днях столкнулась с ситуацией, когда для меня "зонтик" = кросс-командный проект, для коллеги — кобренд с внешним партнером.
2️⃣ Определите продукт и его границы.
О чем ваш продукт? Кто его потребитель? Это не просто набор фич. Это должен быть четко очерченный набор ценностей, которые продукт приносит.
3️⃣ Поймите, как ваш продукт монетизируется.
Даже если он внутренний (например, платформа), его монетизация — это сокращение затрат других подразделений. Это тоже нужно учитывать.
4️⃣ Решите, нужна ли вам документация наружу.
Если у вас платформа (а уж если не платформа - тем более), подумайте, будете ли вы публиковать документацию (и какую ее часть) для внешних пользователей. Это определяет, как выстроить структуру документов.
5️⃣ Сосредоточьтесь на “бережливой документации”.
Не нужно писать многотомные руководства, которые никто не будет читать. Актуализируйте, если не постоянно, то — регулярно. Разделяйте информацию на уровне: стратегический (общее представление) и тактический (подробные инструкции).
6️⃣ Интегрируйте документацию в процесс работы.
Документация должна быть не только полезной, но и доступной, а также стать частью вашего рабочего процесса! Документы — это артефакты фиксации мыслей, и именно через них можно идеи челенджить, тестировать, да и риски митигировать и нивелировать на этапе документирования приятнее, чем в проде :)
Хорошая документация — это баланс между пустотой и хаосом. Это не только описание текущего состояния, но и инструмент, который помогает новым людям разобраться в проекте, а продукту — развиваться.
А как вы справляетесь с “проклятиями” документации? Какие аксиомы лежат в базисе ваших артефактов? Делитесь опытом, мне будет интересно! 😊
#architecture #project_management