Подготовка технической документации на ПО

Работающая система ещё не означает, что в её устройстве легко разобраться. Программисты знают код до мелочей, администратор помнит особенности настройки, пользователи привыкли к интерфейсу. Но стоит подключиться новому специалисту или возникнуть нестандартной задаче, как появляются вопросы. Где найти нужную функцию? В каком порядке действовать? Как проверить результат?
Ответы должны быть в технической документации. Иначе даже обычная операция может потребовать обращения к разработчику, а при передаче продукта заказчику придётся заново выяснять то, что уже обсуждали в ходе реализации.
Для подготовки руководств нужно заранее собрать исходные описания, проверить их актуальность и согласовать оформление. Когда эти вопросы остаются открытыми до заключительного этапа, на документирование приходится отводить время одновременно с другими задачами команды.
Если речь идёт о крупном программном комплексе, объём работы может достигать нескольких сотен листов. При этом разработчики продолжают заниматься продуктом, и выделить отдельного специалиста на составление руководств получается далеко не всегда.
В статье расскажем о двух проектах НооСофт, в которых нам предстояло разобраться в сложных системах и подготовить более тысячи страниц технической документации по ГОСТам.
Два проекта с разными исходными данными
Первая компания-разработчик и интегратор геоаналитических решений обратилась к нам за подготовкой документации для подсистемы ГИС, в которой пользователи работают с картой и пространственными данными.
В распоряжении технического писателя была версия продукта, адаптированная для конкретного клиента. Специалист самостоятельно изучал интерфейс, проходил рабочие сценарии и сопоставлял увиденное с исходными описаниями.
Чтобы составить инструкцию, недостаточно знать, что функция существует. Нужно выяснить, где она находится, как пользователь к ней обращается, какие действия выполняет и что должно произойти в результате.
При сверке алгоритмов действий с предоставленными материалами предстояло установить, какие операции относятся к доступной версии продукта и как их следует называть в руководствах. Технический писатель фиксировал такие вопросы и запрашивал сведения, необходимые для точного описания.
Второй проект НооСофт выполнял для компании Полимедиа. Документирование касалось отдельных механизмов BI-платформы Visiology, включающих несколько взаимосвязанных компонентов. Подготовку исходных материалов взяла на себя команда Полимедиа. Опираясь на сведения, полученные от их специалистов, НооСофт разрабатывал запрошенные руководства.
Такой формат позволял готовить описания на основе информации команды продукта и приводить материалы к согласованной структуре с учётом требований ГОСТов.
Более 1000 страниц документации
Состав комплектов различался в зависимости от заказчика. Для первого требовались три документа:
- Руководство пользователя. В нём описываются доступные операции и порядок работы с ними: куда перейти, что сделать и каким должен быть результат.
- Руководство администратора. Здесь нужны сведения о настройке и обслуживании системы. Получить их только из пользовательского интерфейса невозможно, поэтому требовалась дополнительная информация от специалистов заказчика.
- Программа и методика предварительных испытаний компонентов подсистемы. Эти документы определяют порядок проверки функций. Значительная часть сведений оформлялась в таблицах; содержание уточняли по мере поступления данных и согласования состава испытаний.
Для Полимедиа готовили руководства по отдельным модулям платформы.
Общий объём подготовленных комплектов превысил 1000 страниц. На это ушло около 500 часов.
Документирование велось с учётом актуального состояния продуктов: для одних функций были доступны рабочие сценарии, для других — описания или макеты. Поэтому при составлении материалов важно было различать подтверждённое поведение системы и сведения, требующие уточнения.
Как проверять исходные сведения
Одна из трудоёмких задач технического документирования — сопоставить описание функции с доступным интерфейсом. Возможность может относиться к другой версии или контуру продукта, называться иначе либо требовать дополнительного пояснения. Прежде чем включать пользовательский сценарий в руководство, важно установить, какая информация подтверждена.
Вопросы для уточнения фиксировали в таблице. Вместо общего запроса на материалы формулировали конкретные пункты: какое название использовать, как совершается операция, где можно проверить функцию.
При необходимости просили предоставить инструкции, иллюстрации или пояснения разработчиков. Недостающие действия нельзя додумывать. Даже скриншот не всегда позволяет восстановить весь пользовательский сценарий. Он показывает расположение элементов, но не обязательно объясняет, что произойдёт после нажатия кнопки и какие условия должны быть выполнены.
Фрагменты, для которых не хватало подтверждённых сведений, дорабатывали после получения уточнений. Такой порядок помогал отделять проверенную информацию от предположений.
Как мы работали с ГОСТами
Для обоих проектов заказчики определили шесть стандартов:
- ГОСТ Р 2.105–2019 — «Единая система конструкторской документации. Общие требования к текстовым документам»;
- ГОСТ 34.201–2020 — «Информационные технологии. Комплекс стандартов на автоматизированные системы. Виды, комплектность и обозначение документов при создании автоматизированных систем»;
- ГОСТ 34.602–2020 — «Информационные технологии. Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы»;
- ГОСТ Р 59792–2021 — «Информационные технологии. Комплекс стандартов на автоматизированные системы. Виды испытаний автоматизированных систем»;
- ГОСТ Р 59795–2021 — «Информационные технологии. Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Требования к содержанию документов»;
- ГОСТ Р 59853–2021 — «Информационные технологии. Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Термины и определения».
Одного перечня было недостаточно. Для каждого вида документации предстояло выявить применимые положения, состав разделов и необходимую подробность описаний. Например, руководство пользователя и программа испытаний решают совершенно разные задачи, соответственно требования к ним не будут одинаковы.
Нельзя обойти стороной и единообразие. Когда над крупным программным комплексом работают несколько компаний, каждая из них может по-своему описывать отдельные компоненты системы. Даже один и тот же элемент интерфейса порой получает разные названия, что создаёт путаницу для интегратора, которому необходимо объединить все части в целое.
В подготовленных материалах специалисты НооСофт унифицировали терминологию и структуру разделов, а также согласовали уровень детализации. Это позволило упростить последующее объединение материалов с документацией других участников проекта.
*Приведённый перечень ГОСТов не ограничивает возможности НооСофт. В новом проекте состав документов и применимые стандарты определяются его задачами и требованиями заказчика.
Согласование заняло отдельное место
После подготовки текст проходит проверку у специалистов, которые отвечают за разные стороны работы системы. Это самостоятельный этап документирования.
В описанных проектах были задействованы представители нескольких организаций. При обсуждении учитывали замечания к структуре, изложению функций и оформлению, чтобы материалы соответствовали установленным требованиям.
Когда сведения проходят через отдельных участников, особенно важно заранее определить, кто уточняет технические детали, кто проверяет содержание и как фиксируются принятые формулировки. Это помогает сохранять последовательность работы над разделами.
Чтобы не откладывать проверку на последний момент, мы передавали руководства частями, иногда отдельными главами. Пока заказчик изучал очередной раздел, технический писатель занимался следующим. Так правки можно было учитывать по ходу документирования.
«Команда в это время была полностью занята разработкой и испытаниями, и отвлекать её на сотни листов документации по ГОСТ значило рисковать сроками. Поэтому мы передали эту работу техническим писателям НооСофт, но встроили её в свой процесс: назначили ответственных за уточнения и проверяли руководства по главам. Правки не копились к концу этапа, а на проверке содержательных замечаний к документации не было» — Полесский Д.А. ведущий рук.проектов Полимедиа.
Пожелания касались единообразия изложения и оформления. По ним и дорабатывали материалы.
Такой опыт показывает, насколько полезно в начале согласовать порядок проверки разделов и сбора замечаний. При нескольких участниках важно, чтобы уточнения по функциям и терминологии попадали в одну актуальную версию текста, а решения по спорным формулировкам были зафиксированы.
Как начать подготовку документации
Когда эту обязанность поручают разработчикам, им приходится делить время между ней и развитием продукта. Изучение ГОСТов, описание функций, оформление и согласование могут занять сотни часов. При этом основные задачи команды никуда не исчезают.
НооСофт готов взять эту работу на себя. Мы разберёмся в устройстве системы, рассмотрим имеющиеся сведения, составим необходимый комплект по требованиям ГОСТов и доведём его до конца.
Причём приходить к нам с завершённым техническим заданием необязательно.
Если у вас уже есть требования или шаблоны, присылайте их вместе с кратким описанием продукта. Если пока непонятно, что именно нужно подготовить, расскажите, для каких целей: внутреннего использования, передачи заказчику, проведения испытаний или приёмки системы.
На первой встрече обсудим задачу, доступы к продукту, исходные данные и сроки. Определим, какая информация потребуется от ваших специалистов, кто будет проверять результат и как организовать согласование. После этого сможем оценить трудозатраты и предложить план работы.
Пусть разработчики занимаются кодом, а документацию доверьте тем, кто готов в ней разобраться.





