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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Подробнее по ссылке.