Динамическая документация — новый уровень эффективности разработки в IT

Документация проектов разработки ПО — болевая точка многих IT-компаний. Как правило, существуют две крайности: или она ведется "на коленке", или, напротив, чрезвычайно подробно и забюрократизированно. В первом случае начинается хаос при любых изменениях в разработке, во втором — все процессы затягиваются сверх меры из-за многочисленных согласований и необходимости вручную вносить корректировки в тысячи документов. Рассказываем о разработанной Андреем Самойловым методике, позволяющей сохранить и полноту информации в документации, и делать работу с ней максимально гибкой и быстрой.

К идее этого проекта Андрей Самойлов пришел благодаря опыту работы в ИТ-департаментах крупных банков. Так, ранее специалист успешно реализовал две крупные задачи в области создания систем документации для одного из крупных коммерческих банков. Первая — унифицированная документация контроля качества, которая позволила сформировать единое пространство и методологию документирования для сотни сотрудников этого направления. Вторая — система учета серверных мощностей тестового ландшафта. Андрей Самойлов создал методологию описания ресурсов, правил эксплуатации, методологического назначения, ролей и групп ответственности, что позволило произвести эффективную закупку дополнительных мощностей и начать проект по масштабному переоснащению тестового ландшафта всего банка.

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

"В больших компаниях документация по проекту может содержать десятки тысяч страниц, — рассказывает Андрей Самойлов. — И есть, например, сотни различных пользователей информационной системы с этой документацией, и каждому нужно найти в этой "Ленинской библиотеке" вручную то, что именно ему нужно. Допустим, одному человеку в этом документе важно содержание одной главы, другому специалисту содержание третьей главы, а четвертому специалисту важен только статус согласования — каждому из них необходимо ознакомиться со всем документом, только чтобы найти важный для них раздел".

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

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

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

Благодаря настройке этого процесса описание патча превратилось в строгую структуру, аналогичную базе данных, а для подготовки релиза потребовалось создать динамический документ, собирающий запросом нужную информацию из нужных задач, к которым привязаны патчи. Сроки работ сократились в два-три раза, а количество конфликтов установки - примерно в пять раз", — объясняет Андрей Самойлов.

Методика Андрея Самойлова позволяет решить ещё одну важную проблему, с которой часто сталкиваются исполнители и заказчики в процессе работы над сложным проектом, во время его внедрения и после, при необходимости внесения обновлений. В большинстве российских компаний традиционно сложился несбалансированный подход к процессу документирования разработки программного обеспечения. Либо разработка ведется бессистемно, либо, наоборот, все процессы слишком тщательно и подробно фиксируются и проходят многоступенчатое согласование. В первом случае разработка программного обеспечения проходит быстро, при этом процесс документируется хаотично: готовый продукт выходит быстро, но любая возникающая проблема в его работе становится "пожарной", и никто не знает, как ее решить, к кому обращаться, кто ответственный за тот или иной функционал. Во втором случае, наоборот, любая мелочь многократно задокументирована, согласована и проверена, а внесение любых изменений при этом становится болезненным: корректировки в одном документе влияют на тысячи других взаимосвязанных страниц, что невероятно замедляет даже самые банальные процессы.

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

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

Чтобы внедрить свою методику в производственный процесс, Андрею Самойлову понадобились не только технические компетенции, но и навыки менеджера:

«Мне доводилось внедрять свои инструменты в нескольких компаниях, ведущих ИТ-разработку. Несмотря на то, что каждый раз это разработка новых приемов в рамках моего подхода, главной целью является создание более удобного процесса или практики. Конечно, не всегда это проходит гладко, поэтому я уверен, что внедрение должно проходить поэтапно и в тесном контакте с пользователем, чтобы не вызвать отторжения. Со временем лучшие инструменты успешно приживаются, а остальные уходят на доработку».

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

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

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

"Мне хочется усовершенствовать этот инструментарий так, чтобы, он предоставлял информацию целевым образом, выборка из документа предоставлялась бы в зависимости от того, кто ее будет читать, кто получатель. Эта же идея заложена в мониторинг качества документации. Например, каждый читающий заходит и выделяет ту область текста, которую он собирается копировать или прочитать, в том числе, на интуитивном уровне. Отслеживая это, мы понимаем, какая часть документации востребована у разработчиков, какая у тестировщиков и так далее, можем создать "тепловую карту", — отмечает Самойлов

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

Автор Дмитрий Олейник.