Документация в порядке

Пост о том, зачем и как аккуратно вести проектную документацию, даже если у вас Agile. Делюсь перечнем и структурой полезных документов и рекомендациями по работе с ними.

Речь пойдет в основном о внутренних документах, которые обычно никто не просит писать, но которые на самом деле нужны команде.

Небольшое лирическое отступление про то, что меня вдохновило на написание этого текста:

При разработке ИТ-систем мне кажется очень важным поддерживать порядок в документации. Это и есть та самая “стена”, на фоне которой разворачивается проектная жизнь — на нее смотрят и делают выводы, что это за проект и как там все работает.

Зачем писать

Бывают проекты и без документации — но скорее всего так получилось не от хорошей жизни, либо никто из участников не знает, что “так можно было”.

Обоснованность наличия документации — отдельная тема, об этом писали, например, здесь.

Если коротко — то “без бумажки ты букашка”. Наша память обманчива и недолговечна. Завтрашний ты обманешь себя сегодняшнего или наоборот. Придет новый человек или уйдет старый — каждый такой финт будет стоить вам дорого. Без общей картины вы будете заниматься микроменеджментом и разработкой того, что уже кем-то сделано, но он забыл вам об этом сказать. Будете делать петли и вставлять друг другу палки в колеса. А через полгода мучительно вспоминать, зачем нужен этот огромный кусок кода, который все тормозит. И это даже не касаясь кейса, когда вы заказали разработку на стороне.

Что писать

Сложно представить проект, на котором документация не нужна совсем. Другой вопрос, что она может быть разного формата и в разных объемах, покрывать разные аспекты системы.

Например, на старте проекта с гибкой методологией велика вероятность, что все еще раз 5 поменяется до момента внедрения. Поэтому подробное техническое описание может быть лишней тратой времени. А вот позитивный сценарий — на какие кнопки в каком порядке пользователь нажимает, какие данные вводит — нужен всем членам команды. И при частых его изменениях особенно важно, чтобы у всех было единое понимание текущей версии процесса.

Легче кому-то одному потратить пару часов на документирование, чем всей команде постоянно проверять свою память.

То есть даже когда обстоятельства не в пользу полноценного описания системы и вы работаете в “Agile”-режиме — важно понимать, что какая-то документация существенно облегчит процесс разработки и принесет много пользы.

Как выбрать то, что нужно документировать — дело каждого проекта. Приведу структуру и состав документации, которые считаю полезными.

Необходимый минимум

На мой взгляд документы, которые важны практически на любом проекте, это:

1. Документ-маршрутизатор

   Место, откуда можно добраться до всех артефактов проекта. Это может быть страница в Confluence, пространство Notion или просто Google-документ. Важно создать единую точку входа — пусть там будут только ссылки на разные инструменты и источники, но вам не придется запоминать пути поиска нужного файла.  

   

2. Артефакты проектных процессов

   Флоу процесса разработки, статусная модель задач, доски с беклогом, план-график проекта, список нужных контактов и пр. Наличие такой документации налаживает процесс работы и делает его более комфортным. А также сильно разгружает аналитика/менеджера/тимлида и всех, кого волнует выполнение задач и сроки.

   

3. Глоссарий

   Приводит всех участников работ к одному понятийному полю. Особенно полезен там, где много специальных терминов или разночтений. На некоторых проектах достаточно всего нескольких определений, но полезно все же их зафиксировать.

4. Артефакты бизнес-потребности и бизнес-процесса

   Agile-манифест гласит: “Работающий продукт важнее исчерпывающей документации”. Но нельзя разработать работающий “как надо” продукт без четкого понимания, что же мы все-таки делаем и зачем. Бизнес-требования, схема процесса или просто письмо с постановкой от заказчика — что-то должно быть.

   

5. Концептуальная модель системы

   Описание основных сущностей, верхнеуровневая функциональность и взаимодействие с другими системами.

   Используйте IDEF0, «дорожки» BPMN, просто схему или текстовый перечень — главное обозначить принцип работы вашей системы.

   

6. Классы пользователей и уровни доступа

   Такая памятка очень поможет при разработке требований — ведь всегда надо понимать, для кого и что делается. А путаница и в итоге неверный доступ — потенциально большие проблемы.

7. Cценарии использования

   Даже если вы не используете этот инструмент для разработки требований — какой-то сценарий работы системы у вас есть. Это может быть инструкция для пользователей или тех. поддержки. Или последовательность вызовов с параметрами, если речь идет о взаимодействии систем.

8. Логика работы системы

   По коду или БД не всегда получается понять смысл функционала. Например, формула расчета стоимости скорее всего задается бизнес-правилами, о которых коду ничего не известно.

   Эти данные так или иначе передаются разработчикам при постановке задачи. Удобно сразу их записывать в виде читаемого документа, а в задачах вставлять только ссылки на место в этом документе. А если в тот же документ прикреплять тест-кейсы — будет совсем красиво.

   

9. Описание АПИ

   Да пребудет с нами swagger и стандартный формат ответа методов. Если с вами интегрируются внешние компании — не обойтись и без подробного описания параметров.

10. Тестовые данные

    Среды, учетные записи и все, что нужно, чтобы не сводить с ума тестировщика однообразными вопросами.

11. Ограничения/нефункциональные требования

    Вы договорились, что рассчитываете максимум на 100 пользователей? Делаете импорт справочников раз в сутки в час ночи? Внешняя система не умеет принимать какие-то значения? Сделайте приятно себе в будущем — запишите все эти детали.

Другие типы документов

Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта:

1. Архитектура системы

   Иногда необходимо детальное описание сервисов и их взаимодействия. Например, если сервисов несколько и они взаимосвязаны, или если архитектура микросервисная.

2. Требования к данным

   Логическая модель, требования к составу и формату данных, особенности работы с ними и пр. Всё это не всегда покрывается характеристиками БД — в таком случае полезно зафиксировать их в отдельном документе.

   Сюда же можно добавить соглашения о формате БД — принципы наименования таблиц и атрибутов, используемые типы данных и пр.

3. UX/UI макеты и прототипы

   Их лучше сразу собирать в одном известном всем месте и держать в актуальном состоянии.

   С чехардой в макетах разбираться потом очень сложно. Просто представьте, что у вас хотя бы 3 экрана и у каждого хотя бы по 5 состояний. И аналитик, дизайнер и разработчики смотрят каждый в свой проект в фигме.

   

4. Описание интеграций

   Протоколы интеграций, спецификации АПИ, процессы и потоки данных и всё, что необходимо для избежания недоразумений при взаимодействии с другими системами.

   

5. Безопасность

   В целом параметры безопасности могут быть описаны вместе с доступами или нефункциональными требованиями, либо же наследоваться от общего контура ИТ компании. Но бывают системы с приоритетом или особым подходом к этой характеристике.

6. Внешняя документация

   Документы для пользователей, партнеров, надзорных органов и прочие артефакты, которыми система общается с внешним миром.

Не трудно заметить, что бОльшая часть перечисленной информации скорее всего на проекте уже есть. Но она может быть разбросана по сохраненным сообщениям, личным папкам, письмам и прочему открытому космосу. Собрать это в единую структуру и оформить — не так долго, но эта работа может заметно сократить издержки на лишние вопросы, забытые задачи, кривой функционал и прочие неприятные факторы.

Как писать

Несколько инсайтов о работе с документацией:

• Не забывайте про актуальность

  Стоит писать только ту документацию, которую вы сможете поддерживать в актуальном состоянии.

  При отсутствии описания люди начнут общаться друг с другом и у них есть шанс добраться до истины. При неактуальной документации — все будут на нее смотреть и делать неправильно.

  

• Неоформленные артефакты — тоже документация

  Удобно складывать в одно место те артефакты, которые нет возможности обработать и хорошо оформить.

  Например, письма с договоренностями, примеры данных, ссылки и пр. Иначе вы скорее всего просто забудете, что такое когда-то было. Ну и в случае, если вдруг потребуется подтвердить какое-то согласование — не придется тратить час на поиск нужного письма в почтовом клиенте.

• Растите культуру документирования в команде

  Не обязательно всё должен документировать один человек, особенно если в команде нет специальной роли для этого. Даже не технические писатели умеют складывать ссылки в нужное место, писать чек-листы, комментировать макеты и прочее.

  Важно договориться, как такая документация будет поддерживаться.

  

• Комментарии в коде не всегда спасают

  Структура кода не обязана повторять структуру процесса/функционала и, тем более, бизнес- и пользовательских требований. Поэтому из кода можно понять «как» работает система, но на вопросы «зачем?», «почему?» и «как должна?» отвечает именно проектная документация.

• Планируйте и декомпозируйте работу с документацией

  Документирование — это задача, которую легко разбить на небольшие отрезки времени и “размазать” по спринту.

  Когда-то я бронировала в календаре последние 2 часа пятницы на составление/актуализацию документации. Принимать решения в это время опасно, к тому же эта деятельность помогает подвести итоги рабочей недели и запланировать следующую.

• Закрывайте техдолг

  При введении функционала в эксплуатацию важно выделить время на дооформление хвостов. Иначе не видать спокойной поддержки и доработки системы.

  Понять, чего не хватает, просто: представьте, что вы приходите на этот проект сейчас, и никто из предыдущей команды с вами поговорить не может.

  

• Больше схем и диаграмм

  Визуальная информация воспринимается легче и быстрее, лучше запоминается. Чем больше данных вы представите графически — тем доступнее и короче будет документация.

  Поможет изучение графических нотаций и UML, практика их применения, а также замечательная книга «Говори на языке диаграмм».

• Учитесь писать нехудожественные тексты

  Навык написания текстов сильно ускоряет процесс документирования и повышает его качество. Рекомендую использовать https://glvrd.ru. Плюс по возможности почитать «Пиши, сокращай» и «Бизнес-копирайтинг». Так и работа быстрее пойдет, и тексты станут понятнее и приятнее.

  Вот еще хороший доклад на тему «Как писать полезные технические тексты».

Как итог

Не обязательно подробно документировать всё, или хотя бы выполнять «необходимый минимум» из этой статьи. Всегда полезно сверять часы с реальностью и понимать — что действительно нужно и поможет достичь цели.

Но важно знать, какие есть инструменты и практики и как это делают в идеальном мире. Тогда вы поймете, на чем основывать свою работу, чтобы не изобретать велосипед и не напарываться на издревле известные грабли.

Даже если у вас нет ТЗ с тезаурусом и перечнем иллюстраций — структурированное и понятное хранение имеющейся документации облегчит жизнь всей команды. А также сподвигнет вас и коллег более собранно и ответственно относиться к проекту.