Сложности документирования, с которыми мне приходилось сталкиваться при работе на разных проектах, описаны в посте "7 ошибок документирования".
А что вы как project manager можете сделать для улучшения процессов связанных с документированием?
Советы и рекомендации - ниже.
Поехали!
1. Выберите правильный инструментарий
От content collaboration software вам нужно:
- легкий в использовании функционал по работе с разметкой, таблицами, форматированием текста;
- поддержка версионности документов;
- возможности просмотра изменений между двумя версиями документа;
Спасибо, Кэп!возможности коллективной работы.
Три варианта, с которыми приходилось работать:
- Jira + Confluence
- Jira + Ms Word
- Redmine + MediaWiki
Mediawiki. “Дешево, но сердито”. Сложный функционал редактирования (особенно табличных данных) компенсирован низкой стоимостью решения. Устанавливали различные плагины, но все равно оказалось не очень удобно.
MS Word. Отличные возможности для редактирования контента, но отсутствие поддержки коллективной работы. Как выход - можно использовать систему контроля версий.
Confluence. Удобно управлять контентом, есть интеграция с Jira, поддержка коллективной работы. Но стоит денег.
Самый удобный вариант - Jira+Confluence. Его и буду рассматривать в качестве примера в следующих пунктах.
2. Внедрите документирование в процесс разработки
- Как начать писать документацию и не забывать ее актуализировать? Сделайте написание документации обязательной частью процесса разработки! При чем не на уровне декларации “Нужно!”, а потому что процесс будет останавливаться-замедляться.
- Документация должна стать основой общения участников процесса разработки - аналитиков, разработчиков, тестировщиков и т.д.
- Документация должна быть единственным “источником правды”. Что не написано на странице в Confluence - не может рассматриваться как договоренность.
- Все ценное, что было обсуждено устно, написано в чатах, нарисовано в блокнотах должно быть обязательно зафиксировано в Confluence.
- Откажитесь от использования Jira для описания требований в тексте тикета. Вместо этого - используйте ccылку на описание требования в Confluence.
- Используйте задачи в Jira как отправную точку для grooming meeting. Выстраивайте задачи в порядке приоритета - упорядочите обсуждения user story.
- Один из критериев готовности задачи к передаче в разработку - наличие описанного требования в Confluence.
- Следите за тем, чтобы вся значимая информация о требовании была отображена в Confluence.
- Прививайте команде культуру бережного обращения с информацией в Confluence.
3. Использовать версионирование документов
- Описывайте только финальный вариант требования. Что, где и как должно поменяться покажет Confluence c помощью функции Compare selected versions. Это и время экономит, и количество ошибок уменьшает.
- В задаче в Jira - ссылайтесь на конкретную версию страницы в Confluence. Появится возможность работать над новой редакцией документа без влияния на тот вариант, который уже отдан в разработку.
- Альтернативный вариант - в Confluence указать ссылку на задачу Jira (используя магию Jira Issues Macro). Получаем двустороннюю трассировку “требование-задача”. Но теряем преимущество связанное с возможностью работать с разными версиями страницы.
4. Разработать стандарты
- Разработайте глоссарий. Выглядит как избыточный артефакт, но когда при обсуждениях начали называть одну из сущностей пятью разными терминами(было и такое), то пришлось договориться о единой терминологии и зафиксировать это в виде документа.
- Разработайте шаблон структуры требований. Это ускорит написание требований и позволит избежать потери важной информации. Иногда подходит простенькая структура user story, иногда на поиск и разработку подходящих шаблонов может уйти несколько месяцев.
- Опишите процесс управления требованиями и документацией. Да, кажется, что редко кто читает такое. Но на практике - значительно экономит время при вводе нового члена команды и обучение существующих.
- В Confluence есть шаблон требований “из коробки”. Используйте его на старте процесса внедрения документирования.
- Когда появится понимание какой шаблон нужен конкретно в вашем проекте - создавайте пользовательские шаблоны.
Заключение
Для меня ответ очевиден - да, нужна. И не только для требований.
А как же тезис Working software over comprehensive documentation из agile manifesto?
Соблюдается! Вносите в документы только “необходимую и достаточную” информацию. Не превращайте ее в "избыточную".
Улучшайте процессы, внедряйте документирование! )
