Пост о том, зачем и как аккуратно вести проектную документацию, даже если у вас Agile. Делюсь перечнем и структурой полезных документов и рекомендациями по работе с ними.
Речь пойдет в основном о внутренних документах, которые обычно никто не просит писать, но которые на самом деле нужны команде.
Небольшое лирическое отступление про то, что меня вдохновило на написание этого текста:
Теория разбитых окон
В криминологии есть так называемая теория разбитых окон: «Если в здании разбито одно стекло и никто его не заменяет, то через некоторое время в этом здании не останется ни одного целого окна». То есть, согласно теории, если порядок не поддерживается - люди охотнее его нарушают и не следуют правилам.
Теорию подтверждают эксперименты социологов из Нидерландов. В одном из них ученые приклеивали к рулям припаркованных велосипедов рекламные буклеты и убирали из окрестности все урны. При этом на стене рядом с велосипедами висело заметное объявление о запрете граффити. Для экспериментальной группы исследователи обеспечили сплошь разрисованную граффити стену, а для контрольной - чистую. В результате, у чистой стены выбросили на улицу или перевесили флаеры на чужой велосипед 25% группы из 77 человек, а у раскрашенной - 69%.
Считаю, что принцип теории можно распространить практически на все сферы жизни человека: чистота и порядок провоцируют на созидание и продуктивность, убирают элементы хаоса и отвлекающие факторы. Однако, конечно, лучше оставлять пространство для творчества и не сковывать себя абсолютной “идеальностью”.
При разработке ИТ-систем мне кажется очень важным поддерживать порядок в документации. Это и есть та самая “стена”, на фоне которой разворачивается проектная жизнь - на нее смотрят и делают выводы, что это за проект и как там все работает.
Зачем писать
Бывают проекты и без документации - но скорее всего так получилось не от хорошей жизни, либо никто из участников не знает, что “так можно было”.
Обоснованность наличия документации - отдельная тема, об этом писали, например, здесь.
Если коротко - то “без бумажки ты букашка”. Наша память обманчива и недолговечна. Завтрашний ты обманешь себя сегодняшнего или наоборот. Придет новый человек или уйдет старый - каждый такой финт будет стоить вам дорого. Без общей картины вы будете заниматься микроменеджментом и разработкой того, что уже кем-то сделано, но он забыл вам об этом сказать. Будете делать петли и вставлять друг другу палки в колеса. А через полгода мучительно вспоминать, зачем нужен этот огромный кусок кода, который все тормозит. И это даже не касаясь кейса, когда вы заказали разработку на стороне.
Что писать
Сложно представить проект, на котором документация не нужна совсем. Другой вопрос, что она может быть разного формата и в разных объемах, покрывать разные аспекты системы.
Например, на старте проекта с гибкой методологией велика вероятность, что все еще раз 5 поменяется до момента внедрения. Поэтому подробное техническое описание может быть лишней тратой времени. А вот позитивный сценарий - на какие кнопки в каком порядке пользователь нажимает, какие данные вводит - нужен всем членам команды. И при частых его изменениях особенно важно, чтобы у всех было единое понимание текущей версии процесса.
Легче кому-то одному потратить пару часов на документирование, чем всей команде постоянно проверять свою память.
То есть даже когда обстоятельства не в пользу полноценного описания системы и вы работаете в “Agile”-режиме - важно понимать, что какая-то документация существенно облегчит процесс разработки и принесет много пользы.
Как выбрать то, что нужно документировать - дело каждого проекта. Приведу структуру и состав документации, которые считаю полезными.
Необходимый минимум
На мой взгляд документы, которые важны практически на любом проекте, это:
Документ-маршрутизатор
Место, откуда можно добраться до всех артефактов проекта. Это может быть страница в Confluence, пространство Notion или просто Google-документ. Важно создать единую точку входа - пусть там будут только ссылки на разные инструменты и источники, но вам не придется запоминать пути поиска нужного файла.
Артефакты проектных процессов
Флоу процесса разработки, статусная модель задач, доски с беклогом, план-график проекта, список нужных контактов и пр. Наличие такой документации налаживает процесс работы и делает его более комфортным. А также сильно разгружает аналитика/менеджера/тимлида и всех, кого волнует выполнение задач и сроки.
Глоссарий
Приводит всех участников работ к одному понятийному полю. Особенно полезен там, где много специальных терминов или разночтений. На некоторых проектах достаточно всего нескольких определений, но полезно все же их зафиксировать.
Артефакты бизнес-потребности и бизнес-процесса
Agile-манифест гласит: “Работающий продукт важнее исчерпывающей документации”. Но нельзя разработать работающий “как надо” продукт без четкого понимания, что же мы все-таки делаем и зачем. Бизнес-требования, схема процесса или просто письмо с постановкой от заказчика - что-то должно быть.
Концептуальная модель системы
Описание основных сущностей, верхнеуровневая функциональность и взаимодействие с другими системами.
Используйте IDEF0, "дорожки" BPMN, просто схему или текстовый перечень - главное обозначить принцип работы вашей системы.
Пример верхнеуровнего описания процесса Классы пользователей и уровни доступа
Такая памятка очень поможет при разработке требований - ведь всегда надо понимать, для кого и что делается. А путаница и в итоге неверный доступ - потенциально большие проблемы.
Cценарии использования
Даже если вы не используете этот инструмент для разработки требований - какой-то сценарий работы системы у вас есть. Это может быть инструкция для пользователей или тех. поддержки. Или последовательность вызовов с параметрами, если речь идет о взаимодействии систем.
Логика работы системы
По коду или БД не всегда получается понять смысл функционала. Например, формула расчета стоимости скорее всего задается бизнес-правилами, о которых коду ничего не известно.
Эти данные так или иначе передаются разработчикам при постановке задачи. Удобно сразу их записывать в виде читаемого документа, а в задачах вставлять только ссылки на место в этом документе. А если в тот же документ прикреплять тест-кейсы - будет совсем красиво.
Описание АПИ
Да пребудет с нами swagger и стандартный формат ответа методов. Если с вами интегрируются внешние компании - не обойтись и без подробного описания параметров.
Тестовые данные
Среды, учетные записи и все, что нужно, чтобы не сводить с ума тестировщика однообразными вопросами.
Ограничения/нефункциональные требования
Вы договорились, что рассчитываете максимум на 100 пользователей? Делаете импорт справочников раз в сутки в час ночи? Внешняя система не умеет принимать какие-то значения? Сделайте приятно себе в будущем - запишите все эти детали.
Другие типы документов
Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта:
Архитектура системы
Иногда необходимо детальное описание сервисов и их взаимодействия. Например, если сервисов несколько и они взаимосвязаны, или если архитектура микросервисная.
Требования к данным
Логическая модель, требования к составу и формату данных, особенности работы с ними и пр. Всё это не всегда покрывается характеристиками БД - в таком случае полезно зафиксировать их в отдельном документе.
Сюда же можно добавить соглашения о формате БД - принципы наименования таблиц и атрибутов, используемые типы данных и пр.
UX/UI макеты и прототипы
Их лучше сразу собирать в одном известном всем месте и держать в актуальном состоянии.
С чехардой в макетах разбираться потом очень сложно. Просто представьте, что у вас хотя бы 3 экрана и у каждого хотя бы по 5 состояний. И аналитик, дизайнер и разработчики смотрят каждый в свой проект в фигме.
Описание интеграций
Протоколы интеграций, спецификации АПИ, процессы и потоки данных и всё, что необходимо для избежания недоразумений при взаимодействии с другими системами.
Безопасность
В целом параметры безопасности могут быть описаны вместе с доступами или нефункциональными требованиями, либо же наследоваться от общего контура ИТ компании. Но бывают системы с приоритетом или особым подходом к этой характеристике.
Внешняя документация
Документы для пользователей, партнеров, надзорных органов и прочие артефакты, которыми система общается с внешним миром.
Не трудно заметить, что бОльшая часть перечисленной информации скорее всего на проекте уже есть. Но она может быть разбросана по сохраненным сообщениям, личным папкам, письмам и прочему открытому космосу. Собрать это в единую структуру и оформить - не так долго, но эта работа может заметно сократить издержки на лишние вопросы, забытые задачи, кривой функционал и прочие неприятные факторы.
Как писать
Несколько инсайтов о работе с документацией:
Не забывайте про актуальность
Стоит писать только ту документацию, которую вы сможете поддерживать в актуальном состоянии.
При отсутствии описания люди начнут общаться друг с другом и у них есть шанс добраться до истины. При неактуальной документации - все будут на нее смотреть и делать неправильно.
Неоформленные артефакты - тоже документация
Удобно складывать в одно место те артефакты, которые нет возможности обработать и хорошо оформить.
Например, письма с договоренностями, примеры данных, ссылки и пр. Иначе вы скорее всего просто забудете, что такое когда-то было. Ну и в случае, если вдруг потребуется подтвердить какое-то согласование - не придется тратить час на поиск нужного письма в почтовом клиенте.
Растите культуру документирования в команде
Не обязательно всё должен документировать один человек, особенно если в команде нет специальной роли для этого. Даже не технические писатели умеют складывать ссылки в нужное место, писать чек-листы, комментировать макеты и прочее.
Важно договориться, как такая документация будет поддерживаться.
Комментарии в коде не всегда спасают
Структура кода не обязана повторять структуру процесса/функционала и, тем более, бизнес- и пользовательских требований. Поэтому из кода можно понять "как" работает система, но на вопросы "зачем?", "почему?" и "как должна?" отвечает именно проектная документация.
Планируйте и декомпозируйте работу с документацией
Документирование - это задача, которую легко разбить на небольшие отрезки времени и “размазать” по спринту.
Когда-то я бронировала в календаре последние 2 часа пятницы на составление/актуализацию документации. Принимать решения в это время опасно, к тому же эта деятельность помогает подвести итоги рабочей недели и запланировать следующую.
Закрывайте техдолг
При введении функционала в эксплуатацию важно выделить время на дооформление хвостов. Иначе не видать спокойной поддержки и доработки системы.
Понять, чего не хватает, просто: представьте, что вы приходите на этот проект сейчас, и никто из предыдущей команды с вами поговорить не может.
Больше схем и диаграмм
Визуальная информация воспринимается легче и быстрее, лучше запоминается. Чем больше данных вы представите графически - тем доступнее и короче будет документация.
Поможет изучение графических нотаций и UML, практика их применения, а также замечательная книга "Говори на языке диаграмм".
Учитесь писать нехудожественные тексты
Навык написания текстов сильно ускоряет процесс документирования и повышает его качество. Рекомендую использовать https://glvrd.ru. Плюс по возможности почитать "Пиши, сокращай" и "Бизнес-копирайтинг". Так и работа быстрее пойдет, и тексты станут понятнее и приятнее.
Вот еще хороший доклад на тему "Как писать полезные технические тексты".
Как итог
Не обязательно подробно документировать всё, или хотя бы выполнять "необходимый минимум" из этой статьи. Всегда полезно сверять часы с реальностью и понимать - что действительно нужно и поможет достичь цели.
Но важно знать, какие есть инструменты и практики и как это делают в идеальном мире. Тогда вы поймете, на чем основывать свою работу, чтобы не изобретать велосипед и не напарываться на издревле известные грабли.
Даже если у вас нет ТЗ с тезаурусом и перечнем иллюстраций - структурированное и понятное хранение имеющейся документации облегчит жизнь всей команды. А также сподвигнет вас и коллег более собранно и ответственно относиться к проекту.
baeva
Хорошая статья:) Не соглашусь лишь с отнесением описания архитектурных решений в необязательные другие типы документов.
Тема обширна. Возможно, различия в восприятии терминологии, но важные тех. решения должны быть выявлены и обязательно зафиксированы на самом старте проекта, отражены в структуре требований (особенно, если у вас будут логические модели данных в виде ERD-диаграмм или диаграммы классов, например) и проектировании минимально-достаточного «дерева» требований. Или еще аргумент хотя бы с позиции потребностей бизнес-анализа: без арх. решений вы НФТ (производительность, отказоустойчивость, например) ну никак не напишите исчерпывающе.
UX/UI не так категорично, конечно, но я бы тоже отнесла в обязательные.
TatyanaSalnikova Автор
Спасибо за комментарий и обратную связь!
«Другие типы документов» в посте — это не «необязательные», а обязательные на определенных проектах. Необходимый минимум — это те, которые я могу написать под все проекты, которые видела.
А вот UX/UI нет в бековских системах (а где есть фронт — макеты будут 99%), в простых системах архитектуру вполне заменяет концептуальная модель, как мне кажется.
baeva
Возможно, я неверно поняла фразу «Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта»:)
Концептуальная модель (точнее то, что вы ею называете; для меня понятие концептуальной модели все же ближе к понятию модели данных (логической модели) или концептуальной модели данных в терминах UML, а у вас модель БП верхнего уровня в нотации IDEF0; сущности описывают ERD и UML Class Diagram) и технологический стек — это немного о разном, как мне кажется. Тех. моменты решения, которые стоит учесть на этапе анализа, есть всегда, независимо от того, «простая система или сложная».
>> А вот UX/UI нет в бековских системах (а где есть фронт — макеты будут 99%), в простых системах архитектуру вполне заменяет концептуальная модель, как мне кажется.
Макеты да, а UX ;)
Но, это все придирки, повторюсь:) Статья очень структурна и полезна.
TatyanaSalnikova Автор
Я бы сказала, что у меня концептуальная модель — это функциональная модель. БП может в себя включать кучу всего вне системного контура и у него другие задачи. Для меня концептуальная модель — это обозначение основных функций системы и принципа ее работы. Если система простая и ее делают хорошие разработчики — технические нюансы можем обговарить примерно там же, так как их немного. Но, конечно, в идеальном варианте хорошо иметь более проработанную документацию по архитектуре решения.
Cогласна c Вами, спасибо за полезный комментарий.
Хочется придумать побольше примеров таких тех. моментов для одного сервиса: субд важна, количество БД, реляционка или нет, тип интеграций (шины, очереди, FTP, REST, SOAP), если стек не выбираем — тоже могут быть нюансы, конечно, бекапы, логирование.
У Вас есть какие-то еще примеры?
baeva
>> БП может в себя включать кучу всего вне системного контура и у него другие задачи.
БП — да, а БП, подлежащий автоматизации, всегда мапится на функции системы.
И я бы все же разделяла понятия как в терминах у Вигерса (логическую модель данных он часто заменяет синонимом концептуальной) и общепринятых стандартов, например, UML (Class Diagram в UML или ERD у аналитиков так и называется концептуальной моделью предметной области в терминах сущностей (классов), их атрибутов и связей). Я понимаю что у вас концептуальная модель системы как бы, а не данных, но такого термина я не встречаю в обиходе.
>> У Вас есть какие-то еще примеры?
Тут я все же больше имела ввиду важные моменты на фазе инициации разработки: технологический стек реализации и иные нюансы, которые должны быть на входе у архитекторов при проектировании или создании тех. дизайна системы с учетом инфраструктур, кроссплатформенности, сред развертывания, интеграций, миграции данных, перспектив масштабирования и т.д.
То, что перечислили вы это уже более глубокие моменты последующего функционального анализа (технического, системного) и действительно не всегда могут быть в пакете итоговых артефактов для условно простых систем.
baeva
Кстати тут и подтвердилось мое предположение в первом комментарии о различии в восприятии терминологии в отношении архитектурных решений:)