Зачем нужна документация IT-проекта и как её вести

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

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

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

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

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

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

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

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

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

Вот самые частые из них.

• Теряется важная информация. Например, шаблоны баг-репортов и тест-кейсов для каждого этапа разработки. Без них на стадии тестирования возникают проблемы, когда команда понимает, что не хватает информации для отладки.
• Новичкам труднее адаптироваться. Документация — это ещё и база для грамотного онбординга. Если её нет или она минимальная, новым сотрудникам придётся отвлекать коллег вопросами по пустякам. Из-за этого может замедлиться работа всей команды, а с ней и релиз продукта.
• Есть риск, что продукт окажется дороже. Без документации легко упустить баги — потому что нет чётких инструкций, что и как проверять. Тестировщики рано или поздно выявят ошибки, а разработчики перепишут код, но на всё это нужно время и деньги — поэтому растёт вероятность перерасхода бюджета. Как итог, клиент начнёт терять лояльность, так как увидит хаос и дополнительные расходы.

Подытожим: хорошая документация помогает свести ошибки в проекте к минимуму. А ещё оградить команду от выгорания.

В нём прописаны:

• цели проекта;
• ожидаемый функционал;
• требования к качеству продукта;
• критерии оценки проекта — например, удобство интерфейса;
• ограничения: сроки, ресурсы, технологии и другие условия, которые влияют на реализацию.

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

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

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

Вот пример:

• первый месяц — разработка интерфейса для учеников;
• второй месяц — создание функционала для преподавателей, включая настройку курсов;
• третий месяц — подключение и настройка модулей для приёма платежей.

Также в плане указывается бюджет — на каждую задачу либо общий по проекту.

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

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

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

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

В неё входят баг-репорты и тест-кейсы — документы, где описывают найденные ошибки и способы их исправления. Они помогают не только фиксировать проблемы, но и отслеживать их статус.

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

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

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

Пример: в руководстве для учеников онлайн-школы могут быть гайды по регистрации, оплате занятий и просмотру лекций. Для преподавателей — инструкции по загрузке роликов, созданию конференций и управлению курсами.

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

Зачем: чтобы команда работала быстро и слаженно.

Как: назначить ответственных за ключевые этапы. Контроль документации проекта обычно лежит на нескольких сотрудниках. Рассмотрим их задачи подробнее.

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

Зачем: чтобы файлы вышли понятными и полезными для конкретной группы. Напомним, проектная документация создаётся для проджект-менеджера и команды разработки.

Как: подумать, кому будет полезна документация. Затем подробно расписать, с какими проблемами сталкиваются специалисты каждый день.

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

Зачем: чтобы систематизировать информацию, которая уже есть и выявить пробелы в документации. Например, у команды есть базовое ТЗ, но все детали обсуждались с клиентом отдельно в чате.

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

Зачем: чтобы удобно хранить и актуализировать информацию.

Как: использовать корпоративную базу знаний. Например, в системе Minerva Knowledge можно собирать и оформлять документацию проекта, работать с кодом и настраивать систему уведомлений обо всех изменениях.

База знаний интегрируется с системами вроде Jira и Trello, что помогает командам не только отслеживать прогресс по задачам, но и получать доступ к документам, которые объясняют процессы или содержат рекомендации.

Кроме того, Minerva Knowledge включает ИИ-помощник Copilot. Он позволяет сотрудникам получать информацию даже за пределами базы знаний. Например, находить документацию по конкретным библиотекам и фреймворкам. Copilot подключается к рабочим системам и может предоставлять данные прямо в среде разработки, когда это нужно.

Зачем: чтобы на основе FAQ сформировать структуру и содержание базы знаний по проекту.

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

Зачем: чтобы поэтапно согласовать содержимое документации. А ещё не запутаться в массиве информации.

Как: определить основные разделы документации проекта и продумать, какие категории и подкатегории нужно использовать. Это поможет структурировать базу знаний. Затем согласовать «каркас» документации с командой. Если будет необходимо, дополнить или убрать лишние пункты — и приступить к самой фактуре.

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

Зачем: чтобы документация была полезной и лёгкой для восприятия. Иначе в ней нет смысла: команде будет проще обращаться напрямую к коллегам, чем читать базу данных.

Как: посмотреть на текст с позиции того, кто видит материалы впервые. Затем ответить на вопросы:

• Всё ли понятно?
• Нет ли перегруза терминами?
• Если дать эту базу данных джуну, он найдёт ответ на свой вопрос?

Зачем: чтобы документация всегда оставалась актуальной и полезной.

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

1. Команда понимает, какой продукт разрабатывает и какая у него основная цель.
2. Участники чётко представляют, что происходит на каждом этапе проекта.
3. Члены команды вносят информацию по установленным правилам, так что остальные сотрудники сразу понимают, о чём речь.
4. В процессах почти нет сбоев, за исключением форс-мажоров; команда выполняет задачи в срок и с минимальным количеством багов.
5. Новичкам легко адаптироваться, а ответы на популярные вопросы они всегда могут найти в базе данных.
6. Процессы не замораживаются при смене ключевых сотрудников.

Если на все вопросы ответ «Да», то вы создали документацию, которая закрывает потребности вашей команды.