Всем привет!
Если вы читали 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
Вместо того что бы сосредоточить усилия на содержании, неудобные средства работы с текстом могут значительно отвлекать на то что бы добиться приемлемой формы.
А это - лишний раздражитель.
Заключение
При настройке процесса работы с документацией необходимо уделить внимание и таким аспектам:
- внедрение в процесс разработки;
- версионирование документов;
- возможности коллективной работы;
- наличие стандартизированной структуры описания;
- выбор правильного инструментария.
Схему работы с документацией,
которая решает указанные
проблемы (и опробованную на моих проектах), я опишу во второй части.
