Привет! Меня зовут Максим Павлов, я управляющий партнёр KTS и отвечаю за направление системной и бизнес-аналитики.
Некоторые команды относятся к написанию документации весьма догматично — либо пишут всегда, либо не пишут вообще. Мы в KTS стараемся избегать каких-то постулатов и всегда отталкиваться от конкретного кейса.
В материале расскажу, какие в этом вопросе бывают подходы, их плюсы и минусы, и какого подхода придерживаемся мы.
Содержание:
Что мы называем документацией
Сразу обозначу: в этом материале пойдет речь не о документировании кода проекта и не о пользовательской документации, а обо всех остальных ее видах.
Конечно, продукт надо делать так, чтобы пользователю документация вообще была не нужна. Но если вы разрабатываете сложные конструкторы или инструменты автоматизации, то без нее не обойтись.
Рассмотрим два самых частых подхода к формированию документации.
Вариант 1: Единая точка правды
В таком варианте существует единое место, где в унифицированном формате описана документация по проекту. Команда считает этот артефакт самым правильным и актуальным с точки зрения описания работы проекта, и при возникновении каких-то изменений или принятии новых решений на дальнейших этапах процесса сразу обновляет документацию.
Вот что может происходить на проектах, где самая полноценная документация находится в одном месте. Допустим, команда описала концепцию проекта, спроектировала функционал, сделала дизайн-макеты. Один из подходов – начать готовить документацию именно на этом этапе. Затем она бьется на задачи, которые уходят в таск-трекер, где их подхватывают разработчики. Какие проблемы могут быть у такого подхода:
Большинство задач после их постановки дополнительно обсуждаются и претерпевают изменения
Скорее всего, у разработчика по задаче возникнут дополнительные вопросы и уточнения, как бы четко она ни была поставлена
В некоторых случаях разработчик в процессе оценки или реализации задачи находит более оптимальные варианты ее решения
Поставленные дедлайны могут потребовать от команды дополнительной гибкости в принятии решений по проекту и каких-то изменений в постановке задач
В каждом из этих случаев команде приходится частично переписывать уже готовую документацию. Разработчики, в свою очередь, либо ждут ее актуализации, чтобы приступить к выполнению задачи, либо начинают работать до того, как она была изменена. Это чревато тем, что понимание задачи разработчиком и человеком, который обновляет документацию, может разойтись, и выполненная задача не будет соответствовать новому элементу документации.
➕ В каждый момент времени на проекте есть актуальная документация, к которой могут обратиться все участники команды…
➖ …Но команда потратила время и ресурсы, нужные для разработки продукта, на постоянную стыковку артефактов друг с другом
Вариант 2: Последовательность уточняющих артефактов
Другой подход, которого мы придерживаемся в KTS, – это создание последовательных артефактов документации. Каждый из артефактов может противоречить предыдущим, если на этапе его разработки принимались решения по изменению функционала проекта.
При этом следующий артефакт является более актуальной, но не обязательно полной версией документации. Расскажу подробно, как это происходит.
На этапе проработки концепта проекта создается вижн (vision): общие формулировки, описывающие действия определенных модулей или же всего продукта, взаимодействие пользователя с продуктом или продукта с другим продуктом. Это могут быть доски в Miro или обычные текстовые файлы.
Следующий этап — создание дизайн-макетов. Здесь могут возникнуть первые разногласия с текстовым описанием продукта: например, макет, нарисованный по вижну, не оправдал ожиданий, и команда решила в нем что-то изменить. Если дальнейшие решения по проекту принимаются на основе этих разногласий — идти и переписывать текстовое описание не нужно. Новый артефакт, в котором отражены эти изменения, становится наиболее актуальным.
После подготовки макетов начинается их декомпозиция и постановка задач разработчикам. И в этот момент также может возникнуть потребность во внесении каких-то изменений. Вот, что это может быть:
Из эстетических соображений дизайнеры нарисовали красную кнопку там, где по логике продукта должна быть зеленая
Команда решила поменять текстовки в некоторых кнопках или тултипах
В каждом из этих случаев, если изменения макетов кажутся команде необходимыми, комментарии к ним также отражаются в задаче. Менять макеты при этом необязательно, потому что просить дизайнера внести эти мелкие изменения — значит, отвлекать его от другой работы и заставлять разработчика ждать. Поэтому в случае небольших изменений макетов проще отразить соответствующие комментарии в задаче. Например, о том, что цвет кнопки должен быть другим, а текста в блоке должно быть меньше.
Задачи в таск-трекере становятся самой актуальной документацией проекта, и обращаться команда будет именно к ним. Все дальнейшие решения, юзкейсы, логика отображения данных, граничные случаи, методы API также описываются в задачах.
В начале проектирования мы мыслим бизнесовым смыслом проекта, и не можем видеть нюансы, которые обязательно возникнут на дальнейших этапах его реализации. С каждым следующим артефактом команда все лучше понимает детали реализации продукта и не возвращается к его первичной концепции. Поэтому в случае конфликтов между версиями документации команда руководствуется решениями, описанными в более поздних артефактах. При этом мы не говорим, что предыдущие артефакты безнадежно устарели: например, если исполнителю непонятны какие-то решения, описанные в макетах, он может найти ответ на свой вопрос в предыдущих артефактах.
➖ Артефакты не согласованы между собой
➕ Команда не тратит лишнее время на шлифовку и стыковку артефактов друг с другом, а занимается написанием документации в тот момент, когда спроектированная часть продукта уже сделана и работает
Вам шашечки или ехать? Наш «научный» эксперимент с документацией
Расскажу о кейсе, который наглядно показывает разницу между этими подходами. Наша команда занималась разработкой нескольких проектов, входивших в одну экосистему в рамках стартапа. Три сервиса этой экосистемы создавали мы, еще над двумя работала другая команда. При этом дата запуска у всех сервисов была одна.
Используя второй подход, к моменту релиза мы успели создать и протестировать на пользователях свои продукты, получить фидбек и на его основе что-то переделать. Хотя подробной документации у нас не было – описание поведения проектов было описано в задачах и дизайн-макетах.
Это тот случай, когда отсутствие документации стало плюсом, потому что проект все еще находился на стадии динамических изменений. В итоге мы написали подробную документацию после бета-теста на основе того, что зашло пользователям.
Другая команда пошла по первому пути. И на момент планируемого релиза у них была написана подробная документация, но не было готового продукта.
Этот кейс подтверждает, что иметь готовую документацию на первых этапах реализации проекта необязательно, а иногда — зацикливание на ней может стоить команде работающего продукта. Если мы имеем дело со сжатыми сроками или ресурсами, возможно, стоит использовать это время для работы над проектом. А документацию подготовить тогда, когда будет понятен его окончательный вид.
В каждом подходе кроются свои нюансы, поэтому выбрать подходящий вариант можно только оценив конкретный проект и ресурсы на его реализацию. В предыдущем материале — о конкретных кейсах, когда нужно и не нужно писать документацию на проекте.
Другие статьи по менеджменту и аналитике: