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