Документация — это база любого проекта. Без неё ломаются процессы: команда путается в сроках и задачах, не успевает выпустить продукт к дедлайну или отдаёт его в прод с большим количеством ошибок.
В статье разберём, из чего обычно состоит документация в IT-проектах и как выстроить процессы её подготовки, обновления и совместной работы с ней.
В статье разберём, из чего обычно состоит документация в IT-проектах и как выстроить процессы её подготовки, обновления и совместной работы с ней.
Что такое документация и зачем её вести
Это материалы, которые описывают проект: его цели, требования к нему, гайды для пользователей, отчёты, ход работы и многое другое. Подробнее разберём это в разделе «Что включает в себя документация».
Данные по проекту нужны, чтобы сотрудники выпускали качественный продукт без критических багов, в сроки и в рамках бюджета, регулярно его обновляли и предоставляли поддержку пользователям.
Есть несколько подходов к управлению документацией проекта — они зависят от методологии, по которой работают сотрудники. Подход влияет и на степень детализации, а также на формат и способ обновления базы.
Например, в Agile ценят гибкость, поэтому документация чаще всего содержит только ключевую информацию. Например, описание работы с продуктом или список задач для следующей версии. Такой формат помогает команде быстро адаптироваться к изменениям в планах и целях.
В Waterfall, наоборот, нужны подробные документации. Здесь проект жёстко привязан к этапам разработки, а изменения требований и задач происходят реже. Поэтому команды стараются фиксировать все детали на каждом этапе.
Данные по проекту нужны, чтобы сотрудники выпускали качественный продукт без критических багов, в сроки и в рамках бюджета, регулярно его обновляли и предоставляли поддержку пользователям.
Есть несколько подходов к управлению документацией проекта — они зависят от методологии, по которой работают сотрудники. Подход влияет и на степень детализации, а также на формат и способ обновления базы.
Например, в Agile ценят гибкость, поэтому документация чаще всего содержит только ключевую информацию. Например, описание работы с продуктом или список задач для следующей версии. Такой формат помогает команде быстро адаптироваться к изменениям в планах и целях.
В Waterfall, наоборот, нужны подробные документации. Здесь проект жёстко привязан к этапам разработки, а изменения требований и задач происходят реже. Поэтому команды стараются фиксировать все детали на каждом этапе.
На практике необходимая документация для проекта часто ведётся хаотично, и у каждого сотрудника свой подход к ней. Например, один специалист подробно расписывает найденный баг, другой ограничивается фразой вроде «не работает кнопка». Иногда отчёт по ошибке может быть настолько непонятным, что приходится тратить время на уточнения.
Поскольку требования к документации проекта нигде не зафиксированы, документацию редко обновляют вовремя. В небольших командах этим занимается тот, у кого нашлось время, а в крупных приоритеты уходят на более срочные дела. Обновление остаётся менее важной задачей. В итоге данные устаревают, работа замедляется — и команда сталкивается с проблемами.
Вот самые частые из них.
Подытожим: хорошая документация помогает свести ошибки в проекте к минимуму. А ещё оградить команду от выгорания.
Поскольку требования к документации проекта нигде не зафиксированы, документацию редко обновляют вовремя. В небольших командах этим занимается тот, у кого нашлось время, а в крупных приоритеты уходят на более срочные дела. Обновление остаётся менее важной задачей. В итоге данные устаревают, работа замедляется — и команда сталкивается с проблемами.
Вот самые частые из них.
- Теряется важная информация. Например, шаблоны баг-репортов и тест-кейсов для каждого этапа разработки. Без них на стадии тестирования возникают проблемы, когда команда понимает, что не хватает информации для отладки.
- Новичкам труднее адаптироваться. Документация — это ещё и база для грамотного онбординга. Если её нет или она минимальная, новым сотрудникам придётся отвлекать коллег вопросами по пустякам. Из-за этого может замедлиться работа всей команды, а с ней и релиз продукта.
- Есть риск, что продукт окажется дороже. Без документации легко упустить баги — потому что нет чётких инструкций, что и как проверять. Тестировщики рано или поздно выявят ошибки, а разработчики перепишут код, но на всё это нужно время и деньги — поэтому растёт вероятность перерасхода бюджета. Как итог, клиент начнёт терять лояльность, так как увидит хаос и дополнительные расходы.
Подытожим: хорошая документация помогает свести ошибки в проекте к минимуму. А ещё оградить команду от выгорания.
Что включает в себя документация проекта
Техническое задание
В нём прописаны:
Команда ориентируется в задачах и понимает, как их решать. Так, в техзадании для сайта школы могут быть указаны:
- цели проекта;
- ожидаемый функционал;
- требования к качеству продукта;
- критерии оценки проекта — например, удобство интерфейса;
- ограничения: сроки, ресурсы, технологии и другие условия, которые влияют на реализацию.
Команда ориентируется в задачах и понимает, как их решать. Так, в техзадании для сайта школы могут быть указаны:
- структура интерфейса, в том числе дизайн личного кабинета ученика и учителя;
- требования к качеству видео и аудио для уроков, например, минимальное разрешение и формат файлов;
- интеграция с системами онлайн-платежей для оплаты курсов и автоматическая выдача квитанций;
- планируемая нагрузка на сервер и рекомендации по выбору хостинга;
- сроки реализации каждой функции, включая запуск системы проверки домашних заданий и выбора тем.
План проекта
Помогает команде отследить ход работ. Содержит список задач с графиком их выполнения и указанием ответственных.
Вот пример:
Также в плане указывается бюджет — на каждую задачу либо общий по проекту.
Вот пример:
- первый месяц — разработка интерфейса для учеников;
- второй месяц — создание функционала для преподавателей, включая настройку курсов;
- третий месяц — подключение и настройка модулей для приёма платежей.
Также в плане указывается бюджет — на каждую задачу либо общий по проекту.
Техническая документация продукта
Подробно описывает структуру решения: из каких компонентов она состоит, как они работают и взаимодействуют.
В техническую документацию включают системные требования, такие как минимальная нагрузка на сервер или поддерживаемые платформы. А ещё ограничения — например, максимальный объём данных для загрузки.
Также здесь описывают функции системы и пояснительные алгоритмы. Например, может быть описан процесс загрузки видео: пользователь отправляет файл, система проверяет его формат и размер, после чего видео сохраняется на сервере или передаётся в облачное хранилище.
Помимо этого, в рабочей документации содержатся инструкции по диагностике, анализу логов и устранению ошибок.
В техническую документацию включают системные требования, такие как минимальная нагрузка на сервер или поддерживаемые платформы. А ещё ограничения — например, максимальный объём данных для загрузки.
Также здесь описывают функции системы и пояснительные алгоритмы. Например, может быть описан процесс загрузки видео: пользователь отправляет файл, система проверяет его формат и размер, после чего видео сохраняется на сервере или передаётся в облачное хранилище.
Помимо этого, в рабочей документации содержатся инструкции по диагностике, анализу логов и устранению ошибок.
Документация для тестировщиков
В неё входят баг-репорты и тест-кейсы — документы, где описывают найденные ошибки и способы их исправления. Они помогают не только фиксировать проблемы, но и отслеживать их статус.
Например, в техническом проекте по разработке сайта тестирование могут проводить после каждого этапа. Сначала создают меню и проверяют его работу: как открываются разделы, правильно ли отображаются ссылки. Ошибки фиксируют в баг-репортах, но исправляют уже на следующем этапе, чтобы не задерживать разработку. Затем проводят повторное тестирование, чтобы убедиться, что новые баги не появились.
Например, в техническом проекте по разработке сайта тестирование могут проводить после каждого этапа. Сначала создают меню и проверяют его работу: как открываются разделы, правильно ли отображаются ссылки. Ошибки фиксируют в баг-репортах, но исправляют уже на следующем этапе, чтобы не задерживать разработку. Затем проводят повторное тестирование, чтобы убедиться, что новые баги не появились.
Инструкции и руководства
Сюда входят справочные материалы для разных аудиторий: команды, смежных отделов и пользователей. Руководства отличаются по содержанию и стилю.
Пример: в руководстве для учеников онлайн-школы могут быть гайды по регистрации, оплате занятий и просмотру лекций. Для преподавателей — инструкции по загрузке роликов, созданию конференций и управлению курсами.
- Для разработчиков инструкции максимально подробные, с технической терминологией. Они включают описание API, архитектуры и процессов разработки.
- Для других отделов документация упрощённая: она не содержит технические термины, но сохраняет все важные детали. Например, как пользоваться внутренними инструментами или работать с отчётами.
- Для пользователей инструкции краткие и практичные. Они помогают разобраться в функционале продукта и дают ответы на частые вопросы.
Пример: в руководстве для учеников онлайн-школы могут быть гайды по регистрации, оплате занятий и просмотру лекций. Для преподавателей — инструкции по загрузке роликов, созданию конференций и управлению курсами.
Как начать вести документацию проекта
Делимся пошаговой инструкцией, которая поможет организовать процесс с нуля и избежать частых ошибок.
Шаг 1. Распределить роли в команде подготовки документации
Зачем: чтобы команда работала быстро и слаженно.
Как: назначить ответственных за ключевые этапы. Контроль документации проекта обычно лежит на нескольких сотрудниках. Рассмотрим их задачи подробнее.
Как: назначить ответственных за ключевые этапы. Контроль документации проекта обычно лежит на нескольких сотрудниках. Рассмотрим их задачи подробнее.
- Проджект-менеджер — отвечает за управление документацией в целом. Он прорабатывает техническое задание с клиентом, следит за тем, чтобы информацию вовремя добавляли и актуализировали, организует подготовку документации проекта и следит за тем, чтобы коллеги закрывали задачи по ней в срок.
- Тимлид — занимается технической стороной, описывает архитектуру и код. Фиксирует, какие технологии используются в работе, как настраивать серверы и другие элементы инфраструктуры. Создаёт инструкции для поддержки и масштабирования продукта.
- Разработчики — обновляют данные. Описывают функции, за которые отвечают, и вносят изменения в документацию, если меняют код. Их задача — сделать так, чтобы техническая информация была понятной и актуальной.
- Технический писатель — занимается оформлением документации проекта. Он описывает сложные аспекты простыми словами без потери смысла. Структурирует данные, формирует руководства и инструкции для пользователей.
- Тестировщик — пишет баг-репорты и тест-кейсы. Он документирует результаты тестирования, которые помогают команде отслеживать прогресс, исправлять проблемы и улучшать качество продукта.
Шаг 2. Определить целевую аудиторию и задачи документации
Зачем: чтобы файлы вышли понятными и полезными для конкретной группы. Напомним, проектная документация создаётся для проджект-менеджера и команды разработки.
Как: подумать, кому будет полезна документация. Затем подробно расписать, с какими проблемами сталкиваются специалисты каждый день.
Например, если команда разработки задерживает выпуск новых версий после исправления ошибок — возможно, стоит сделать чёткие инструкции по тестированию и фиксации багов.
Как: подумать, кому будет полезна документация. Затем подробно расписать, с какими проблемами сталкиваются специалисты каждый день.
Например, если команда разработки задерживает выпуск новых версий после исправления ошибок — возможно, стоит сделать чёткие инструкции по тестированию и фиксации багов.
Шаг 3. Собрать всю информацию по проекту, которая есть
Зачем: чтобы систематизировать информацию, которая уже есть и выявить пробелы в документации. Например, у команды есть базовое ТЗ, но все детали обсуждались с клиентом отдельно в чате.
Как: проверить задачи в таск-трекерах, переписки с клиентом, инструкции, вопросы в командном чате. После этого отсеять ненужное и неактуальное, составить список недостающих сведений. Далее определить, у кого из команды можно их запросить.
Как: проверить задачи в таск-трекерах, переписки с клиентом, инструкции, вопросы в командном чате. После этого отсеять ненужное и неактуальное, составить список недостающих сведений. Далее определить, у кого из команды можно их запросить.
Шаг 4. Выбрать инструменты для работы с документацией проекта
Зачем: чтобы удобно хранить и актуализировать информацию.
Как: использовать корпоративную базу знаний. Например, в системе Minerva Knowledge можно собирать и оформлять документацию проекта, работать с кодом и настраивать систему уведомлений обо всех изменениях.
Как: использовать корпоративную базу знаний. Например, в системе Minerva Knowledge можно собирать и оформлять документацию проекта, работать с кодом и настраивать систему уведомлений обо всех изменениях.
База знаний интегрируется с системами вроде Jira и Trello, что помогает командам не только отслеживать прогресс по задачам, но и получать доступ к документам, которые объясняют процессы или содержат рекомендации.
Кроме того, Minerva Knowledge включает ИИ-помощник Copilot. Он позволяет сотрудникам получать информацию даже за пределами базы знаний. Например, находить документацию по конкретным библиотекам и фреймворкам. Copilot подключается к рабочим системам и может предоставлять данные прямо в среде разработки, когда это нужно.
Кроме того, Minerva Knowledge включает ИИ-помощник Copilot. Он позволяет сотрудникам получать информацию даже за пределами базы знаний. Например, находить документацию по конкретным библиотекам и фреймворкам. Copilot подключается к рабочим системам и может предоставлять данные прямо в среде разработки, когда это нужно.
Шаг 5. Выявить список частых вопросов
Зачем: чтобы на основе FAQ сформировать структуру и содержание базы знаний по проекту.
Как: выяснить, что чаще всего спрашивают коллеги друг у друга, и для удобства разделить вопросы на категории — например, о техническом задании, функционале, ошибках. На этом же этапе можно придумать сценарии взаимодействия с документацией — как человек будет искать решение проблемы в FAQ или изучать новую задачу.
Как: выяснить, что чаще всего спрашивают коллеги друг у друга, и для удобства разделить вопросы на категории — например, о техническом задании, функционале, ошибках. На этом же этапе можно придумать сценарии взаимодействия с документацией — как человек будет искать решение проблемы в FAQ или изучать новую задачу.
Шаг 6. Составить структуру документации проекта и наполнить её данными
Зачем: чтобы поэтапно согласовать содержимое документации. А ещё не запутаться в массиве информации.
Как: определить основные разделы документации проекта и продумать, какие категории и подкатегории нужно использовать. Это поможет структурировать базу знаний. Затем согласовать «каркас» документации с командой. Если будет необходимо, дополнить или убрать лишние пункты — и приступить к самой фактуре.
Начать наполнение базы знаний стоит с самых важных разделов, например, ТЗ и плана и графика работ. А затем добавлять другие материалы, такие как инструкции и FAQ.
Как: определить основные разделы документации проекта и продумать, какие категории и подкатегории нужно использовать. Это поможет структурировать базу знаний. Затем согласовать «каркас» документации с командой. Если будет необходимо, дополнить или убрать лишние пункты — и приступить к самой фактуре.
Начать наполнение базы знаний стоит с самых важных разделов, например, ТЗ и плана и графика работ. А затем добавлять другие материалы, такие как инструкции и FAQ.
Шаг 7. Проверить текст на логику и доступность
Зачем: чтобы документация была полезной и лёгкой для восприятия. Иначе в ней нет смысла: команде будет проще обращаться напрямую к коллегам, чем читать базу данных.
Как: посмотреть на текст с позиции того, кто видит материалы впервые. Затем ответить на вопросы:
Как: посмотреть на текст с позиции того, кто видит материалы впервые. Затем ответить на вопросы:
- Всё ли понятно?
- Нет ли перегруза терминами?
- Если дать эту базу данных джуну, он найдёт ответ на свой вопрос?
Шаг 8. Организовать процесс обновления
Зачем: чтобы документация всегда оставалась актуальной и полезной.
Как: договориться, кто, когда и как часто будет обновлять материалы. Настроить правила уведомлений и отслеживать в системе, что все члены команды ознакомились с изменениями.
Как: договориться, кто, когда и как часто будет обновлять материалы. Настроить правила уведомлений и отслеживать в системе, что все члены команды ознакомились с изменениями.
Чек-лист хорошей документации проекта
- Команда понимает, какой продукт разрабатывает и какая у него основная цель.
- Участники чётко представляют, что происходит на каждом этапе проекта.
- Члены команды вносят информацию по установленным правилам, так что остальные сотрудники сразу понимают, о чём речь.
- В процессах почти нет сбоев, за исключением форс-мажоров; команда выполняет задачи в срок и с минимальным количеством багов.
- Новичкам легко адаптироваться, а ответы на популярные вопросы они всегда могут найти в базе данных.
- Процессы не замораживаются при смене ключевых сотрудников.
Если на все вопросы ответ «Да», то вы создали документацию, которая закрывает потребности вашей команды.
