Привет, Хабр! Меня зовут Евгения Пономарева, я руководитель проектного офиса “Цифровых технологий”, ИТ-”дочки” ДОМ.РФ. В этой статье я расскажу о роли технической документации и роли технического писателя в IT-проектах ДОМ.РФ, а также поговорим о том, как построен процесс документирования в Институте развития, и как измерить качество документации.

«Цифровые технологии» занимаются развитием Единой информационной системы жилищного строительства (ЕИСЖС), привлечением клиентов, операционным сопровождением, а также созданием цифровых коммерческих сервисов, ориентированных на внешний рынок. Создание эффективных инструментов анализа рынка жилья, планирования и контроля его развития необходимо всем заинтересованным в цифровизации строительной отрасли. Отметим сразу, что под развитием мы подразумеваем разработку нового функционала и доработку используемого программного обеспечения.

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

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

Напрашивается вопрос: по каким параметрам мы определили оптимальный состав? Почему их не два или не пять? Ведь объемы документации только увеличиваются по мере развития новых сервисов. За последний год нам удалось оптимизировать работу техписов за счет контроля за эффективностью их работы.

Основной подход заключается в следующем:

Годовой бэклог развития сервисов и создания новых продуктов мы разделяем на трехмесячные периоды, формируя поквартальные продуктовые карты по каждому проекту.
Вся создаваемая документация предварительно фиксируется договорными документами.
Жизненный цикл отчетных материалов отражен на канбан-досках.
На каждого писателя в среднем на квартал приходится 14 комплектов документации.
Среднее время подготовки технического задания с учетом согласований со всеми стейкхолдерами процесса, внесения правок и учета замечаний составляет от трех до 10 рабочих дней. Подготовка комплекта отчетной документации составляет в среднем 14 рабочих дней.

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

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

Технический писатель одновременно является и полноправным участником команды разработки программных решений. Так как нашим заказчиком выступает государственная организация (ДОМ.РФ), то создаваемая документация является обязательным условием передачи ему результатов работ. Проектные документы - это не просто «вода», а отражение стоимости ресурсов/функционала и сроков разрабатываемого продукта. При этом грамотно составленная документация играет также важную роль для погружения новых участников команды в требования к развитию продукта.

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

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

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

Этапы

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

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

В основной состав отчетных документов входят такие документы, как:

Ведомость документов,
Описание постановки задачи. Документ технического проекта,
Матрица ролей и полномочий,
Паспорт роли (для каждой роли),
Руководство пользователя / Руководство администратора,
Программа и методика проведения приемочных испытаний,
Протокол приемочных испытаний.

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

Процесс документирования и метрики

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

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

ГОСТ 34.602-2020 Информационные технологии. Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы;

ГОСТ Р 59795-2021 Информационные технологии. Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Требования к содержанию документов;
ГОСТ Р 59792-2021 Информационные технологии. Комплекс стандартов на автоматизированные системы. Виды испытаний автоматизированных систем;
ГОСТ Р ИСО/МЭК 25023-2021 Системная и программная инженерия. Требования и оценка качества систем и программной продукции (SQuaRE). Измерения качества системы и программной продукции;
ГОСТ Р ИСО/МЭК 25040-2014 Информационные технологии. Системная и программная инженерия. Требования и оценка качества систем и программного обеспечения (SQuaRE). Процесс оценки.

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

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

В настоящее время мы проводим исследования по метрикам эффективности и качества технической документации. Основной акцент делается нами на:

удовлетворенности заказчика;
удовлетворенности пользователей программного продукта;
метрики должны быть: измеримы, однозначны, учитывать специфику заказчика и соответствовать предметной области;

удобство применения технической документации.

Вес каждой метрики состоит из двух значений: 0 и 1.

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

Для управления изменениями, отслеживания времени разработки технической документации, привлечения команды проекта мы создали процесс в Jira со своей статусной моделью движения документов. Это позволило расставлять приоритеты в задачах, вести учет количества закрытых задач, количества задач в работе, почасовой учет времени для закрытия задачи разработки/обновления документации. Частично добились участия команды в оценке качества документации.

В этом году мы решили идти дальше и работаем над улучшением качества разрабатываемой документации. И решили начать с актуализации шаблона технического задания (ТЗ) и создания спецификации стиля. При разработке шаблона ТЗ столкнулись с необходимостью актуализации схем развертывания. С этим нам помогли коллеги из архитектуры и аналитики, которые обновили в wiki разделы с описанием архитектурных решений, Kubernetes и интеграциям, и создали доступные и понятные схемы.

При анализе руководств по стилю мы учитывали опыт таких ГК как Росатом, Ростелеком, Роснефть, анализировали документы Microsoft Style Guide, Google developer documentation style guide, Veeam Technical Writing Style Guide.

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

Роль технической документации в IT-проектах ДОМ.РФ