Всем привет! Вот уже несколько лет я занимаюсь построением процессов и внедрением ITSM-систем. В проектах внедрения систем у заказчика стремлюсь использовать принципы BDD (Behavior Driven Development) и DDD (Documentation Driven Development) и немножко KCS по причине собственной лени (двигатель прогресса!) и сильного нежелания заново возвращаться к «пройденному».

Не секрет, что многие очень не любят писать документацию, а особенно пользовательские инструкции – и я исключением не являюсь. Раньше, когда я работала в эксплуатационном подразделении внутреннего ИТ, меня надо было несколько раз спросить одно и тоже, чтобы я села и написала инструкцию: не спросили – не пишешь.

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

1. Я же уже 100 раз всем все объясняла – так о чем писать?

2. Эти настройки видела неделю назад, и по факту возвращаюсь к ним же, как надоело!

3. Так, а тут что мы имели в виду? Опять перечитывать документы и комментарии…

В общем, все эмоции как правило сводятся к мысли «я опять делаю одно и то же». Тогда на глаза попалась методология KCS, которая помогла сделать первые шаги в направлении «сначала документируй, а потом делай».

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

Но при чем тут вообще перечисленные в заголовке практики? Разберем подробнее.

Пример

В рамках небольшого проекта по внедрению Jira пишем:

1. техническое задание;

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

3. описание API для разработчиков смежных систем (опционально);

4. инструкцию пользователя;

5. инструкцию администратора.  

Техническое задание

Может быть предоставлено заказчиком, может быть заложено в проект внедрения. BDD здесь подходит идеально: просим заказчика или описываем самостоятельно сценарии работы человеческим языком. В дальнейшем расшиваем их на отдельные блоки ТЗ: настройки, процессы, правила переходов и так далее, по тексту задаем вопросы заказчику.

Как правило, для коррекции ТЗ достаточно одного часа коммуникации с заказчиком, чтобы уточнить детали. Плюсом является то, что ТЗ становится ему понятным – заказчик видит в нем собственные мысли, но при этом ему не требуется вникать в технические моменты (или они также достаточно прозрачны). После готовности, к техническому заданию с правками больше не возвращаемся – оно остается в качестве изначального плана работ по системе.

Документация настроек системы

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

Если по мере реализации появляются правки (добавить полей, изменить статусы, где-то добавить логику переходов или ограничения), они также сначала отражаются в документации, и только потом выполняются. В итоге к моменту завершения у нас полностью готова документация системы: она актуальна и учитывает произошедшие изменения.

Описание API для разработчиков смежных систем

Это фрагмент документации настроек, ориентированный исключительно на интеграцию. Пишем его, если интеграция предполагается. Для ускорения процессов интеграции описываем необходимые запросы, структуру, наименования полей (и только тех, что требуются). Если добавляем/убираем поля, то отражаем это в документации. Это сильно снижает объем необходимой синхронизации – разработчик всегда знает, где посмотреть актуальные параметры, вам же не приходится подстраиваться под его график разработки (и да, возвращаться к уже сделанному «через две недели», когда он приступил к своей части).

Инструкция пользователя и инструкция администратора

Пишем их во время тестирования реализованного функционала, дополняем при правках. Проверяем и адаптируем при подготовке к демонстрации.

Итого

• Собрали требования – написали ТЗ – скорректировали с заказчиком;

• Написали документацию – настроили;

• Заказчик попросил что-то изменить – исправили документацию – настроили;

• Написали черновик инструкций – начали тестировать – дополнили инструкции;

• Нашли ошибки – исправили документацию – исправили ошибки – дополнили инструкции;

• Провели обучение – дополнили инструкции (возможно скорректировали документацию и что-то изменили).

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

Что получаем на выходе

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

• Актуальную и полную документацию (что особенно приятно, если проект через некоторое время берется на поддержку);

• Отсутствие задержек в поставках по проекту (не буксуем из-за документации);

• Отсутствие неприятного фактора «описывать целый день, то что уже сделано» (кому-то может и нравится, но не мне).

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

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

P.S. На практике мне приходилось участвовать или наблюдать проекты, где используются другие подходы и это оправданно, но порой приводит к Panic Driven Development =).