Когда я пришла на новый продукт, меня ждал сюрприз: документация, которая должна была объяснить, как всё работает, лежала в папке "Старое/Не трогать".

Её писали 5 лет назад — на коленке. В ней было описано то, что хотели сделать когда-то, а не то, что работало сейчас.

Архитектура менялась 14 раз, процессы перекраивались, а документация осталась в том же виде, как и была — пылилась.

Я поняла: описывать систему придётся самой. Однако описание не рождается из воздуха ➡️ оно рождается из процессов. А процессов тоже не было.

Я села и написала на стикере один вопрос: "Что должно быть описано, чтобы проект не сдох?".

В конце концов родился список священных скрижалей ⬇️

🟠Как работает продукт — что он делает, для кого, из чего состоит; 🟠Как мы разрабатываем задачи — от идеи до релиза, кто за что отвечает на каждом этапе; 🟠Как мы передаём задачи в тестирование — кто, когда, с какими данными, какие критерии готовности; 🟠Как мы выпускаем релизы — это вообще отдельный квест, у каждого продукта свой; 🟠Как мы актуализируем описание системы ПОСЛЕ релиза — спойлер: раньше — никак; 🟠Как мы делаем демо для заказчика и команды — кто, что, когда показывает.  И внутри каждого пункта я насчитала ещё по 5–10 подпунктов: шаблоны постановок, требования к архитектуре, различные гайды. Мы даже дошли до того, что у нас появился пункт "Рецепт крабового салата для команды аналитиков по вторникам" (шучу, но было близко 😁).

И тогда я сделала вывод: описание системы — это не музейный экспонат, а живой организм.

Его надо кормить, обновлять и показывать всем — от стажёра до заказчика. Каждый должен понимать, как работает продукт. Иначе как он поймёт, что делать со своей частью работы?

Живое описание — это то, которое команда открывает каждый день, которое обновляется после каждого релиза, в котором можно написать: "Это уже не так, давайте перепишем".

И команда перепишет, так как это их инструмент, а не чужая бумажка.