Привет! Меня зовут Максим Павлов, я управляющий партнёр KTS и отвечаю за направление системной и бизнес-аналитики.
Подготовка документации — дело затратное. Прежде чем приступать к ней, нужно подумать, действительно ли она нужна, или это делается, потому что «так принято».
Сегодня я подробно остановлюсь на ситуациях, когда написать ее необходимо. Если в одной из них вы узнаете свой проект, документация сильно поможет в его реализации.
Обратите внимание, что речь пойдет не о документировании кода и не пользовательской документации, а обо всех остальных ее видах.
Содержание:
Когда пора писать документацию
Бурный найм или ротация специалистов
Ротация может быть между разными проектами компании, либо между блоками одного большого проекта.
Как правило, подключение новых специалистов необходимо при активном росте продукта, когда текущей скорости команды не хватает. Документация по проектам, над которыми работает команда, позволяет быстро провести онбординг новых специалистов, которые присоединяются к разработке продуктов.
Если документации нет, новые ребята начинают приходить с вопросами к более опытным. Получается парадокс: человек, которого брали в команду, чтобы ускорить работу, наоборот, замедляет ее. И чем больше таких новичков, тем больше вопросов. С документацией новые специалисты быстрее начнут приносить пользу.
Большая команда
Если над проектом работает, допустим, от 3-4 человек на каждой платформе, например на фронтенде, может получиться так, что кто-то из них вообще не прикоснется к коду определенного модуля.
Если одному разработчику придется что-то исправлять или дорабатывать в незнакомом разделе, с актуальной документацией его шансы успешно сделать это самостоятельно резко возрастают. В противном случае может получиться так, что вся команда будет ждать специалиста, который как бы отвечает за эту часть проекта, либо отвлекать его от текущих задач.
Завершение работы над большим блоком и пауза по проекту
Это могут быть цикличные проекты, над которыми команда работает с определенной периодичностью, или просто некий проект, поставленный на холд.
Здесь у команды KTS есть живой пример — личный кабинет для сотрудников Х5 Retail Group, в котором есть модуль ежегодного планирования отпусков. Этот процесс каждый год начинается в октябре и кончается в декабре, и каждый год наши ребята его оптимизируют на основе фидбэка пользователей и HR-специалистов заказчика.
Мы понимаем, что заниматься этим проектом зимой-весной мы не будем – работа по нему начнется в августе-сентябре. В таких случаях важно после каждого завершения работ по проекту описать актуальную документацию по доработанному блоку, чтобы максимально упростить процесс возвращения к этой задаче.
Когда писать документацию рано
Вот мини-чеклист кейсов, когда она точно не нужна:
Проект или модуль проекта часто переделывается
Точно не нужно писать документацию, когда проект находится на этапе постоянных корректировок и изменений. Речь идет не о дополнениях функционала, а о серьезном изменении частей проекта.
В таких случаях уже готовую документацию придется постоянно менять, и бизнес-эффекта на этой стадии от нее будет меньше, чем оверхеда от ее ведения и оформления.
Когда определенная фича или большой раздел находится на этапе проверки гипотезы
Любая фича может как выстрелить, так и показать отрицательный результат после тестирования на пользователях. Если мы изначально понимаем, что можем ее выкинуть, если она не взлетит, то до подтверждения ее жизнеспособности документация не нужна.
Когда продукт еще не запущен
«Работающий продукт важнее исчерпывающей документации», — гласит один из пунктов Agile-манифеста.
Запустить продукт и не иметь документации лучше, чем не запустить продукт, но иметь исчерпывающую документацию.
Это утверждение не касается проектов, связанных с жизнью и здоровьем людей, где риск ошибки очень велик. Но для остальных кейсов это справедливо.
В сухом остатке
Проектная документация — это всегда компромисс. Даже с учетом описанных выше критериев, нужно принимать решение не исходя из каких-то постулатов, а оценив, насколько эффект от написания документации нужного уровня детализации сопоставим с объемом вложений в этот процесс.
В следующей статье я остановлюсь на более глобальном вопросе: стоит ли писать документацию вообще?
Другие статьи по менеджменту и аналитике:
Комментарии (13)
xopen
13.04.2023 09:07+4Документацию надо писать всегда, даже когда кажется, что нет смысла. Это дисциплинирует людей. Никто не будет через год писать документацию, если год ее никто не писал.
Например по пунктам:
-
Когда продукт еще не запущен
Как минимум на середине документация понадобится отделу QA и техписам, чтобы начать писать пользовательскую документацию. А если вы сделаете продукт раньше документации, то вас еще и Support проклянет.
-
Когда определенная фича или большой раздел находится на этапе проверки гипотезы
А куда делся документ от Product Management? Кто хочет, чего хочет, какие use-case? Где начальная архитектура, чтобы все таки обсудить ее до того, как начать код писать?
-
Проект или модуль проекта часто переделывается
А как другие отделы узнают, что изменились интерфейсы взаимодействия? Или может быть их модуль теперь вообще не нужен? Как вообще другие программисты узнают, что и почему переделалось?
В больших проектах без документации нельзя. Точка.
uwriter Автор
13.04.2023 09:07Вот чтобы переломить ситуацию и чтобы люди не писали документацию, когда не понимают зачем они в данном конкретном случае её пишут я и написал статью
Насчет того, что через год писать документацию скорее соглашусь, но при этом у меня есть много примеров, когда несколько месяцев и даже лет писали систему и когда стало нужно ее передавать другой команде на сопровождение была написана документация. Так что тут тоже дело в целесообразности -- когда она нужна, её нужно писать, когда не нужна -- не нужно
Насчет документации для отдела QA тоже не соглашусь. Каждая задача, которую делал разработчик и которая передается тестировщику должна быть подробно описана. В таком случае само описание задачи и является куском документации. Тоже самое и с техписами -- если есть потребность на каждую функцию написать пользовательскую документацию, то получается это всего лишь еще один пункт в процессе работы над задачей перед ее завершением
"Куда делся документ от Product Management?" -- тут я тоже глубоко убеждён, что прежде чем разработчик приступает к написанию кода у него должна быть подробно описанная задача в таск трекере. Постановщик может вести для себя какие-то дополнительные документы или просто макеты в фигме с описанием пользовательского пути или всё что угодно. Но у разработчика должна быть декомпозированная и описанная задача, а перед стартом нового блока -- весь перечень задач по новому блоку чтобы спроектировать архитектуру
Насчет сваггеров, по которым взаимодействую 2 отдела, разумеется контракты должны выполняться, но это всё равно не значит, что должна быть написана документация. Есть сваггер -- хорошо, нет сваггера, но договорились как тут надо взаимодействовать и в таске написали сигнатуру метода -- тоже нормально. Сама по себе документация не спасёт от того, что нерадивые смежники изменят API к сожалению, это надо решать на уровне процессов.
А насчет того, как отдел узнает, что их модуль не нужен -- ну тут точно вопрос не в документации, а в управлении выше управления конкретным отделом, это тоже должно делаться на уровне процессов. Будет странно, если разработчик прочитает какой-то кусок документации и узнает оттуда, что его отдел не нужен...
Corsonamor
13.04.2023 09:07Ещё всегда нравилось, как из пункта аджайл-манифеста по своему желанию люди выбрасывают слово "исчерпывающая" или игнорируют его, делая вывод, что документация в аджайле не обязательна, этакий бантик сверху.
uwriter Автор
13.04.2023 09:07Тут соглашусь. Манифест говорит не об обязательности или необязательности, а о том, что важнее, чему должен отдаваться приоритет
-
klimkinMD
13.04.2023 09:07Запустить продукт и не иметь документации лучше, чем не запустить продукт, но иметь исчерпывающую документацию.
Лютый популизм! (Продукт без документации -- нонсенс; о какой "исчерпывающей" документации речь, если продукта нет)
И, да, конечно: "программный код -- лучшая документация", -- от пользователей из бухгалтерии отдельное человеческое спасибо!
uwriter Автор
13.04.2023 09:07Ну исчерпывающую документацию по ненаписанному продукту очень даже можно написать еще до того как продукт создан. Компании, работающие с гос заказчиками делают это постоянно, есть даже отдельный этап -- написание исчерпывающего ТЗ и ЧТЗ по ГОСТу.
Так что не согласен с тем, что это популизм, к сожалению это неприятная действительность
А насчет бухгалтерии -- я в начале статьи писал, что рассказываю о всей документации кроме пользовательской, но сам конечно придерживаюсь подхода, что если к интерфейсу нужна документация, то тут всего 2 причины:
1. Либо пользователь недостаточно "опытный пользователь ПК", как он написал в своем резюме
2. Либо интерфейс плохо спроектирован
klimkinMD
13.04.2023 09:07ТЗ и ЧТЗ, написанные на первом этапе, это не "исчерпывающая" документация! И отнюдь не конечный вариант.
А про отсутствующую документацию Вы в космической или атомной отрасли (ПО) расскажите. (но оно летает и работает)
uwriter Автор
13.04.2023 09:07Ну насчет необходимости документации в производстве ракет и ядерных реакторов думаю никто спорить не будет. Но мы с вами не запускаем ракеты в космос (по крайней мере я не запускаю), в продуктах, которые мы делаем важнее дать пользователям продукт, даже если там будет где-то в глубине один хитрый баг. Самолёт не упадет, реактор не взорвется от этого
Gradiens
13.04.2023 09:07Понимаете, чаще у нас есть следующие фазы:
Проект активно развивается, перспективы просто космические, все бегут за морковкой (которая спереди) Но все постоянно меняется, и вот вообще не до документации. Да и зачем писать, все равно все переделаем.
Проект (ну или фаза проекта) близки к завершению. Все забыли про морковку спереди. Все чувствуют морковку сзади. Документация? Какая еще документация! У нас дедлайн на носу! Вот доделаем, и тогда...
Проект (или фаза проекта) доделаны, все выдыхают. Кто с облегчением, а кто, хм.. с иными чувстами. Потому как морковка сзади все-таки настигла.
Пауза? Какая пауза? Мы и так сорвали сроки. Нам и так еще позавчера надо было впрягаться в следующий проект (или фазу). Документация? Ну да... обещали... но вот совсем некогда. И завтра тоже некогда. Да и неинтересно. Да и уже пашем над следующим проектом.
Что, для сдачи проекта документация все-таки нужна? Блин. Ну ладно, щас по-быстрому накидаем. Но совсем по-быстрому. Минимальный объем, чтобы просто "закрыть" этап. Не потому что мы вредные или ленивые. Просто со 100%-й занятостью по новым задачам тратить время (зачастую, уже после рабочего дня) на документацию к уже завершенному проекту - ну такое себе развлечение.
uwriter Автор
13.04.2023 09:07Слышу боль госухи и фикс прайс проектов:)
Звучит справедливо, но если наладить подходящую схему контрактования и адекватное планирование, то получается хорошо. Особенно, если есть отдельный человек, который может описывать то, что сделали пока другие делают уже следующее
nirom
Документация бывает разная.
Мне как-то пришлось погружаться в проект, в котором всю документацию писали джуны, собственно 90% коллектива были джуны. Это было что-то типа такого: чтобы провести документ, - нажмите кнопку провести документ, чтобы создать элемент справочника, нажмите кнопку создать, и так 120 страниц.
Толку от такой документации - ноль, такую документацию лучше не писать.
uwriter Автор
Вот именно поэтому я и написал эту статью -- многие подходят к задаче написания документации "шоб было", тратят время впустую, а продукт от этого ничего не приобретает или в худшем случае еще и теряет