Рефакторинг документации при разработке ПО: как привести в порядок спецификацию проекта

Создание спецификации проекта – важная часть процесса разработки программного обеспечения. Этот документ содержит технические и бизнес-требования к продукту, а также инструкции для всех участников проектной команды, позволяющие им четко понимать конечную цель и координировать действия. Зачастую по разным причинам аналитику сложно поддерживать спецификацию в надлежащем виде на протяжении всего жизненного цикла программы. Ведущий системный аналитик IT_ONE Татьяна Долгина объясняет, как упорядочить документацию с помощью принципов рефакторинга – подобных тем, что используются в кодировании.

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

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

– на крупном проекте создаются объемные многоуровневые документы, путаница в которых может превратиться в серьезную проблему при развитии продукта,

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

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

Предпосылки к рефакторингу документации

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

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

Второе: вносить изменения в документ становится всё сложнее. Для этого каждый раз требуется долго искать нужный фрагмент. Бывает также, что над документом работают несколько человек, и каждый вносит изменения без согласования друг с другом или не вносит вообще.

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

Четвертое: ответы находятся, но для их получения требуется избыточное количество времени.

Пятое: найденные ответы неактуальны. Например, в спецификации не отражены существенные доработки системы.

Цели и алгоритм рефакторинга

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

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

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

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

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

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

Мы выделяем следующие этапы рефакторинга:

– постановка цели: что и каким образом нужно улучшить, чего необходимо добиться,

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

– определение и расстановка приоритетов (в случае, если на полноценное улучшение времени не хватает),

– составление плана,

– поиск инструментов, позволяющих автоматизировать процесс (например, подготовка диаграмм в PlantUML, улучшение стиля текста с помощью GPT-модели),

– непосредственно рефакторинг,

– оценка результата, ревью и согласование изменений.

Основные направления рефакторинга

Рефакторинг спецификации предусматривает улучшение его синтаксических и семантических характеристик.

К синтаксису документа в данном контексте мы относим его структуру (заголовки, иерархию, разбивку на страницы и разделы), форматирование (выделения, списки, таблицы), стиль (сокращения, терминология, особое оформление).

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

Конкретные действия аналитика по этим направлениям такие:

– пересмотр структуры документа: разбивки на страницы, иерархии компонентов, внутренних взаимосвязей (гипертекста),

– упрощение языка документа, избавление от "лишних" слов и не имеющих значимости сведений,

– создание единой и понятной системы терминологии и сокращений (термины и сокращения лучше вынести в отдельный блок спецификации),

– добавление визуальных элементов в достаточном количестве (таблиц, диаграмм, схем, иллюстраций),

– устранение визуального шума: всех элементов, не несущих смысловой нагрузки и мешающих восприятию,

– проверка однозначности используемых в документе полей и терминов,

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

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

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

Признаки качественно проведенного рефакторинга:

– каждому элементу спецификации отведена собственная страница,

– повторяющиеся элементы вынесены на отдельные страницы, соединены гиперссылками или вложениями,

– разные слои проекта (бэк, фронт, бизнес, интеграции и т. д.) разнесены,

– соблюден баланс текста и иллюстраций,

– в документе минимум визуального шума.

Преимущества, получаемые в результате рефакторинга

Рефакторинг способствует поддержанию в проекте качественной документации и гарантирует команде разработки

– четкие, однозначные и понятные требования,

– улучшение коммуникаций между системным аналитиком и разработчиками,

– быстрый онбординг для новичков,

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

– рост производительности,

– снижение количества ошибок.

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

– прозрачность и контроль процессов разработки,

– улучшение и точность планирования,

– сокращение затрат на исправление ошибок и онбординг,

– улучшение репутации компании как ИТ-работодателя,

– повышение доверия к компании со стороны заказчиков, создание положительного впечатления от профессионализма команд разработки (это особенно существенно, если компания занимается заказной разработкой).

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

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