Исправляем ошибки документирования

Всем привет!

Сложности документирования, с которыми мне приходилось сталкиваться при работе на разных проектах, описаны в посте "7 ошибок документирования".

А что вы как project manager можете сделать для  улучшения процессов связанных с документированием?

Советы и рекомендации - ниже.

Поехали!

1. Выберите правильный инструментарий

Найдите эффективную для вашего проекта связку task tracker  + content collaboration software.

От 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?
Соблюдается!  Вносите в документы только “необходимую и достаточную” информацию. Не превращайте ее в "избыточную".

Улучшайте процессы, внедряйте документирование! )

7 ошибок документирования

Всем привет!

Если вы читали Agile Manifesto, то, вероятно, обратили внимание на пункт касающийся документации - “Working software over comprehensive documentation”.

Нужна или не нужна документация? Если нужна, то в каком количестве и что именно описывать? Вопросы интересные, но их обсуждение выходит за рамки данного поста. 

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

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

Для простоты описания предположим, что:

•     решение "Документации на проекте быть!" принято;
•     авторы документации будут называться “аналитиками”;
•     речь идет об описании требований  (“ТЗ”, “спецификация”, “описание фич”, “user stories”, etc.).

 

Ошибки, проблемы, нюансы

1. отсутствие понимания сложности

Писать документы начали. Что-то даже описали. Потом забросили, потому что есть более важные дела. Позже вернулись к описанию, но не всего (другие приоритеты). Часть требований - описана,  другая- описана не полностью, третья - вообще без описания.  Какие-то документы уже неактуальны. Но не понятно какие.

Пользоваться документацией невозможно, выяснять как именно что-то реализовано или должно быть реализовано приходится по-старинке (т.е. без документации). Вердикт команды - "эти waterfall-практики нам не подходят, не будем тратить время на бесполезную документацию!".

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

Готовы ли вы к тому, что на документацию будет необходимо выделять ресурс?

Мало создать документ. Его нужно поддерживать в актуальном состоянии.
И чем более нестабильные требования/бизнес/заказчик, тем больше вы будете тратить ресурс на то что бы это делать.И делать это нужно будет на регулярной основе.

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

2. необязательное документирование

"Сначала зарелизим на продакшн, а опишем потом...".

Хорошо, если "потом" таки настанет.

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

А документация со временем так и не появляется либо окончательно теряет актуальность.

3. документация не вовремя

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

К моменту возврата к работе над фичей документацию пришлось практически полностью переписать. В итоге - потратили в два раза больше времени на описание.

Чем ближе к agile (и, соответственно, дальше от waterfall) у вас методология выбрана для проекта, тем больше шансов что написанная "в стол" документация окажется устаревшей.

4. хаос коллективной работы

Аналитик описал требования к фиче в google docs.

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

совершенно очевидные для аналитика (т.е. в google docs так и не появились, а остались в месенджере).

Представитель заказчика немного подкорректировал и финализировал описания в google docs. Но...  уже после того аналитик перенес все описания в задачу tasktracker'а и отдал в работу на тех.команду.

В конце-концов фичу реализовали. Но с овертаймами, демотивированной командой и слегка перенервничавшим заказчиком.

Какие проблемы получили?

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

Добавить к этому списку дополнительные усложняющие обстоятельства (e.g. сжатые сроки) и головная боль вам как project manager обеспечена!

5. отсутствие версионирования

Аналитик сделал описание нового функционала.

Функционал был достаточно большой, что бы его решили деливерить в нескольких спринтах. Зарелизили в продакшн первую часть.

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

Внесли изменения в SRS по первой части, но вторую часть до продакшена не довели - заказчик поменял приоритеты.

В результате - потеряли описание работающего на продакшене функционала.

Очевидный выход - иметь несколько версий документа . Но сразу же возникают вопросы связанные с одновременной работой нескольких членов команды(аналитики, разработчики, тестировщики) с несколькими версиями одного документа - как не запутаться?

  

6. нестандартные стандарты

Один аналитик делает описания требований plain текстом. Другой - любит описывать в виде mindmap с короткими пояснениями. Третий - не признает ничего кроме блоксхем. И все трое пишут на трех разных языках. 

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

Ситуация, конечно-же, нереальная и встречалась мне в гораздо более приемлемом варианте.

7.  неудобный инструментарий

"Да не хочу я тут ничего описывать. Неудобно же!" -  сказал
аналитик, пытаясь создать табличку 9 на 64 в формате
wiki markup

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

А это - лишний  раздражитель.

 

Заключение

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

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

Схему работы с документацией, которая решает указанные проблемы (и опробованную на моих проектах),  я опишу во второй части.