Привет! Меня зовут Елена Павлова, и более 10 лет я работаю в сфере IT, была в роли системного и бизнес-аналитика, а сейчас руковожу отделом аналитиков в компании Positive Technologies. Почти 10 лет я работала в финтехе, поэтому примеры в статье будут именно из этой сферы, но все, о чем я пишу, актуально и для других предметных областей — я сама в этом убедилась, сменив домен на информационную безопасность.
Многим аналитикам знакома ситуация: пишешь требования, отдаешь коллегам на ревью и согласование, а дальше отвечаешь на вопросы (иногда на одни и те же от разных людей в команде), что-то уточняешь, добавляешь то, что упустил и не предусмотрел. И в оценке трудоемкости задач вынужден закладывать еще и время для ответов на вопросы. А хочется уже исследовать новую задачу.
Возникает логичный вопрос: можно ли написать такую спецификацию, по которой вопросов не будет вообще? Если ее будут читать, то без вопросов не обойтись. Но снизить их число можно, тем самым сэкономив свое время и время команды.
В этой статье я поделюсь тем, как я это делаю и что помогает мне и моей команде создавать документацию, которую легко читать и понимать.
Для кого пишется документация
У документации, описывающей требования, есть несколько групп потребителей, каждая со своими целями и особенностями:
-
Бизнес-команда
В эту группу входят заказчики (внешние или внутренние), продакты (владельцы и менеджеры продуктов). Им важно, как именно их бизнес-требования будут реализованы в продукте, как он будет выглядеть для пользователя, а также как изменятся бизнес-процессы, с которыми они работают или от которых зависит успех решения.
Чаще всего это люди, чей рабочий день состоит почти из одних встреч, поэтому и документацию они читают там же: одним ухом слушают происходящее, а вторым глазом изучают текст, то есть не очень внимательно.
-
Техническая команда
Архитекторы, разработчики и тестировщики знакомятся с предстоящим проектом и верхнеуровнево оценивают его объем работ на основании документации, затем проектируют решение. Позднее, на этапе реализации, технической команде нужны четкие требования: что именно должно быть сделано и как должно работать.
-
Новые люди в команде
Часто об этой группе забывают при написании требований, но именно они читают документацию внимательнее всех — на этапе онбординга, погружаясь в продукт и специфику предметной области.
Получив свою первую задачу, новый человек захочет быстро понять, к какой части системы эта задача относится, с чем она связана и как работает сейчас.
Но, независимо от целей, всем потребителям хотелось бы, чтобы документацию было легко воспринимать и можно было быстро найти самое нужное.
Критерии качества необходимы, но недостаточны
На мой взгляд, для достижения цели, описанной выше, недостаточно, чтобы написанные требования удовлетворяли критериям качества. И вот что еще я обычно включаю в документацию.
Описание цели разработки и бизнес-контекста
Казалось бы, зачем это писать? Из рассмотренных выше групп читателей первая (бизнес-команда) и так владеет этим контекстом. А второй (технической) это зачем? Вот есть готовые требования — бери да реализуй их. Но понимание того, зачем нужна новая функциональность, где и кем она будет использоваться и как связана с уже существующими возможностями системы, позволяет команде не упустить влияние доработок на существующие функции, заметить ограничения, а еще предложить альтернативные решения, о которых ранее не подумали. Тем самым можно выдавать более качественные решения, если обладать бизнес-контекстом.
Может быть полезно понимание перспектив развития продукта: новое требование постоянное или временное, функциональность будет изменяться через полгода-год?
Временные решения предъявляют менее жесткие требования к сложности дальнейшего сопровождения – на короткий срок эксплуатации можно позволить себе дорогую поддержку, зато сэкономить ресурсы за счет более простой и быстрой разработки (да и «накостылять» можно, раз все равно скоро переделывать). В моем опыте был случай, когда команда узнала, что поток данных будет использоваться всего полгода, и перепроектировала его, тем самым сэкономив пару месяцев на этапе разработки.
Кроме того, понимание ценности работы повышает мотивацию команды.
Краткое описание функциональности
Самая большая моя боль, когда я прихожу на новый проект, — есть куча документации, много низкоуровневых деталей, но общего понимания не складывается. А складывается ощущение, что я собираю паззл из 3000 деталей, а картинки, которая должна получиться, у меня нет. Мне гораздо проще погружаться в новый продукт, когда у каждой спецификации есть короткое, буквально в двух-трех предложениях, описание сути изменений и подсвечены самые важные моменты.
Но и технической команде, давно создающей продукт, легче работать, когда есть краткое описание. На ранних этапах разработки от специалистов требуется предварительная оценка трудоемкости, и, чтобы ее сформировать, нужно понимать скоуп изменений. Большой многостраничный документ сложно удержать в голове, поэтому есть риск что-то упустить, ошибиться с оценкой и планированием и в итоге не успеть закончить разработку к концу проекта.
Да, многие работают по гибким методологиям и точные оценки дают уже на конкретные задачи при планировании ближайших работ, но, как правило, верхнеуровневая оценка тоже есть и используется для среднесрочного и долгосрочного планирования.
И здесь стоит упомянуть бизнес-команду, которая согласовывает документацию, но может читать ее поверхностно и упустить важные моменты, в итоге после выхода в прод поведение системы в каких-то случаях, например в корнер-кейсах, будет для них неожиданным.
Документация мотивации
У людей часто вызывает недоумение, почему котик сидит в коробке, хотя рядом есть мягкая уютная лежанка. Примерно такие же чувства могут вызывать требования, зафиксированные в документации.
Аналитику и его коллегам, которые участвовали в проектировании и принятии решений, уже известно (и потому очевидно), почему сделали именно так (выбрали эту интеграцию, решили хранить или не хранить данные и т. д.). А коллеги, которые в обсуждении не участвовали, задают вопросы: «А почему так? Кажется, лучше будет вот так. Давайте поменяем? А вы учли такой-то кейс?»
Можно, конечно, каждому отвечать и рассказывать, что учитывали, что рассматривали, но я предпочитаю сэкономить свое время и сразу задокументировать причины.
Избегание формулировок business as usual, «стандартное поведение», «как обычно» и подобных
Определяя новое поведение через упоминание старого, вы подразумеваете, что читатель знает, о чем идет речь, или заставляете его в этом разбираться: искать описание этого старого стандартного поведения, как бы перекладывая свою работу на потребителя требований. Можно в дополнение к формулировке business as usual добавить ссылку на старую документацию, где впервые такое поведение появилось, но иногда этого недостаточно, так как приходится переходить по ссылкам, теряя контекст. А чем сложнее читать требования, тем больше будет вопросов, а также ошибок в оценках и сроках.
Моя рекомендация — дать краткое описание, что такое business as usual, и по возможности ссылку на старую документацию. При поверхностном чтении это поможет понять, что происходит, а на этапе реализации позволит быстро сориентироваться, что именно (какую часть кода или, например, текстов об ошибках) из прошлого проекта можно или нужно переиспользовать в новом.
Ссылки на стандарты предметной области
Представим, что мы делаем задачу и нам нужно поддержать новый формат сообщений, определенный некоторым стандартом. Мы описываем маппинг, требования, что сообщение должно соответствовать стандарту, и так далее.
И это вполне понятное и однозначное требование, информация о стандарте и формате публичная, ее (почти) легко загуглить, но разве удобно при чтении требований постоянно бегать в Google? Тем более что результат поиска выдаст стандарт целиком (иногда на несколько десятков или сотен страниц), а в конкретной задаче или фиче нужна только его часть. Поэтому я при написании документации всегда включаю ссылки на используемые стандарты (и их разделы), а также даю краткое описание основных моментов, на которые нужно обратить внимание. Такой подход дает возможность заинтересованным лицам прочитать документ и сформировать верхнеуровневую картину без переходов по ссылкам и без лишних вопросов аналитику (ведь спросить иногда проще, чем искать самому) и сэкономить кучу времени. А новички, пока незнакомые со стандартами вообще, будут особенно благодарны.
Забота о саппорте
Когда мы проектируем систему, чаще всего мы сосредотачиваемся на той функциональности, которую продаем или оговорили с заказчиком, и на пользователях, которые будут этой функциональностью пользоваться. Часто забываем о людях, стоящих за всем этим, — инженерах техподдержки и внедрения.
В зависимости от компании и продукта поддержка может иметь разную структуру. Например, в финтехе есть технический саппорт, который разбирает ошибки в работе приложений и систем, и бизнесовый (так называемый operations), который работает с ошибками в пользовательских операциях (например, ищет непрошедший платеж и при необходимости повторно инициирует бизнес-процесс его обработки).
И та и другая группа — заинтересованные лица и источник требований, которые важно не упустить на этапе проектирования системы. Если не продумать, как и какую именно информацию нужно сохранить в случае ошибок и внештатных ситуаций, разбор и решение инцидентов может потребовать много ручного труда и коммуникаций, тем самым увеличить нагрузку на поддержку и замедлить решение инцидентов. Кстати, журналировать и сохранять вообще все тоже не стоит: будет сложно искать нужную информацию в большом потоке нерелевантных данных.
Знание структуры техподдержки продукта помогает сразу спроектировать систему, которую легко сопровождать. В итоге команде разработки приходится меньше участвовать в этом процессе, а пользовательский опыт клиентов улучшается.
Напоследок пара уточнений:
-
В большом проекте резонно подсветить бизнес-контекст и важные моменты в начале, чтобы человек до чтения понимал, на что обратить внимание.
-
Независимо от того, насколько крупные изменения вносятся и в каком формате они описываются (в отдельной спецификации на каждую доработку или в новой версии проектной документации), всегда следует указывать, чем изменения обусловлены, чтобы команда не чувствовала, что занимается чем-то бесполезным.
Заключение
Итак, подведем итоги. Чтобы техническая документация была действительно качественной, легко читаемой и экономила время команды, могут помочь несколько простых правил:
-
Описываем бизнес-контекст: зачем мы что-то делаем и какую пользу это принесет.
-
Даем краткое, но емкое описание изменений, выделяя ключевые моменты.
-
Указываем обоснование решений прямо в документации.
-
Избегаем расплывчатых формулировок типа «стандартное поведение» и вместо этого добавляем конкретное описание, стандарты и ссылки на них.
-
Помним о том, как проект будет жить после релиза.
Надеюсь, мои лайфхаки помогут и вам в документировании требований и спецификаций. Спасибо, что прочитали статью, делитесь в комментариях своими мыслями и идеями, как сделать документацию более исчерпывающей 😊
Елена Павлова
Руководитель отдела системного и бизнес-анализа Positive Technologies
Автор: ptsecurity
