📚 Документация: продукт, проект или просто боль?

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

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

🔹 Проектный подход: все в одном месте (но на время существования места)
Документирование вокруг конкретных проектов удобно, когда нужно зафиксировать, как происходят изменения. Например:
— Добавляется новая система лояльности к уже существующей.
— Расширяется платежная система, добавляется новый способ оплаты.
➕ Плюс: все изменения зафиксированы в одном месте.
➖ Минус: когда проект завершен, информацию трудно поддерживать, так как она только про проект, а код и продукт - шире, а значит уже через несколько месяцев все написанное становится сложно искать и учитывать в будущем, так как не понятно, как оно встроено в настоящее.

Можно ли сочетать продуктовый и проектный подход? Да, например, создавая кросс-документацию:
✔️В базе знаний остаются продуктовые страницы где поддерживается описание работы продукта в текущий момент.
✔️ Внутри — ссылки на проекты с изменениями, где описано, как они повлияли на систему.
Но здесь важно задать структуру заранее, иначе очень быстро получится каша.

🔹 Документация пост-фактум: инциденты, разборы, ошибки
Почему-то многие считают, что документация — это только про запланированное. Но часто ценные знания появляются после проблем:
📌 Инцидент случился? Фиксируем, что пошло не так и как этого избежать.
📌 Провели пост-мортем? Добавляем информацию в базу знаний, а не оставляем в разрозненных отчетах.
📌 Обнаружили ошибку в логике продукта? Обновляем документацию, а не просто исправляем код.
Без этого документация превращается в музей устаревших артефактов, а ошибки повторяются снова и снова.

🔹 Документация для R&D и исследовательских задач
А вот еще одна проблема — считать, что документация нужна только тому, что уходит в прод. Но ведь исследования, тестирования и проработки концепций тоже требуют фиксации:
📌 Разбираетесь, какие данные можно передавать в API? Запишите.
📌 Исследуете, как новая система интегрируется с вашей? Сделайте описание.
📌 Проверяете, как реагирует сервис на нестандартные запросы? Это тоже часть документации!
Когда подобные вещи фиксируются не в голове и не в разрозненных тасках в Jira, а в удобном формате, они превращаются в ценный источник информации для всей команды.

🔹 Кто отвечает за документацию?
Есть ощущение, что компании осознали:
✔️ Нужны DevOps-инженеры для инфраструктуры.
✔️ Нужны архитекторы, чтобы проектировать систему.
✔️ Нужны админы, чтобы все работало.
Но когда речь заходит про документацию — вдруг оказывается, что ей никто не должен заниматься системно. 🤷‍♀️

В итоге:
— Вся документация хранится в голове у «того самого Васи».
— База знаний — это просто свалка документов без структуры.
— Новый человек тратит месяцы, чтобы разобраться, что вообще происходит.

Кто должен заниматься документацией?
📌 Knowledge-менеджеры — это такие же важные люди, как и архитекторы, если вы строите продукт = база знаний.
📌 Технические писатели — если компания осознает важность удобной и актуальной документации, и готова тратить время на ее поддержку и актуализацию.

📌 Итог: документируете или просто пишете заметки?
Если у вас нет структуры и процессов работы с документацией, то это не база знаний, а просто записи “на память”.

🚀 Подумайте:
✔️ Как у вас сейчас ведется документация?
✔️ Кто отвечает за базу знаний?
✔️ Можно ли по ней легко найти нужную информацию?

А может, у вас все еще действует принцип «спроси у Васи»? 😏

#architecture #project_management