Как мы сократили время на проверку документов в IT с дней до часов
Москва
09 июня 2023
Чтобы помочь IT-командам быстрее реализовывать проекты за счёт «умной» работы с программными документами, мы с командой разработали сервис, который экономит техническому писателю или системному аналитику от 30% времени на подготовку документации.
Началось всё с того, что один наш большой клиент решил заменить весь стек зарубежных продуктов. В этом списке был Confluence. Помимо его обычного применения — ведения базы знаний и систематизации контента, — был нужен функционал для создания и согласования программных документов. Это архитектура и требования для информационных систем, тестовая документация, программа и методика испытаний и прочие необходимые документы, без которых информационная система не может выйти в продакшен.
Когда мы начали разбирать эти процессы, то увидели, что у Confluence для решения этого класса задач есть несколько минусов.
Первый — то, что Confluence, по сути, набор страниц, и работа с контентом идёт в рамках всей страницы. Это ограничивает редактирование и согласование документов, переиспользование контента и так далее.
Второй минус — процесс создания документов происходит как компиляция отдельных страниц на основе данных из внешних систем. Когда какие-то данные в этих системах меняются, это сложно отслеживать — документ нужно перечитывать и править вручную.
При этом документы связаны между собой: если в одном из них что-то поменялось, то правки на других страницах нужно тоже вносить руками. Это значительные трудозатраты: ресурс расходуется и на редактирование, и на последующие проверки.
Мы изучили рынок и обнаружили, что у многих компаний — например, в строительной, юридической и медицинской отраслях — есть запрос на форматирование документов по шаблонам, формирование их на основе данных из внешних систем и переиспользование данных из документа в документ.
В чём особенность работы с документами в IT-сфере?
IT-компаниям приходится разрабатывать, согласовывать и утверждать объёмные многостраничные требования к информационным системам. Если проект большой, то документ может насчитывать до 1000 страниц.
Помимо документов, описывающих архитектуру информационных систем, команда готовит тестовые документы: программу и методику испытаний, протокол приёмо-сдаточных испытаний и прочее, что необходимо для выпуска программных продуктов.
Если говорить о релизном цикле, то он также завязан на программных документах и зависит от статусов их согласования. До выхода релиза документацию должны проверить и согласовать архитекторы корпоративных информационных систем и специалисты по информационной безопасности. А это нередко при работе в Confluence занимает от нескольких недель до нескольких месяцев, особенно при больших объёмах документов, так как сравнивать версии приходится вручную.
Недостатки существующих программ в работе с технической документацией
На подготовку технической документации, необходимой для разработки сложной информационной системы, может затрачиваться полгода и более. Несколько итераций согласования могут прибавить к этому сроку ещё пару месяцев.
Мы проанализировали существующие на рынке решения, чтобы понять, как добиться сокращения издержек времени и сил. Большинство компаний для подготовки документов использует программы Word и Confluence. Стали разбираться, что именно при их применении тормозит процесс подготовки/согласования документации, и обнаружили следующие моменты:
Управление блоками информации
В Word и Confluence работа с текстом ведётся на уровне всего документа: нет возможности автоматически управлять различными разделами. Если нужно скопировать какой-то кусочек из одного документа в другой, то Word предлагает это сделать с помощью сочетания клавиш Ctrl+C/Ctrl+V. А это довольно трудоёмко и порой ведёт к появлению ошибок, связанных с человеческим фактором, — к примеру, можно вставить не туда, куда надо.
Отсутствие шаблонов и правил заполнения
Типовые правила и рекомендации по оформлению документов могут существенно сэкономить время сотрудников, если им не нужно искать и изучать их отдельно. Но когда, например, системный аналитик захочет расписать техническое задание с помощью Word или Confluence, то он или не найдёт в них актуальных шаблонов, или, что скорее всего, найдёт, но не будет им следовать — поменяет название разделов, их содержание и порядок следования по своему разумению. В дальнейшем это приведёт к проблемам при согласовании и правке документа другими специалистами, а всё это — дополнительные трудозатраты.
Проблемы с обнаружением статусов изменений
Сравнивая версии документов, подготовленные с помощью традиционных программ, специалист вынужден заново перечитывать все 200, 500, а иногда и 700 страниц, чтобы найти и согласовать обновления. Разницу посмотреть невозможно — Word или Confluence такое чаще всего не вытягивают и просто падают. Неудивительно, что при таких трудозатратах на проверку и согласование только одного документа может уйти несколько месяцев.
Проблемы с редактированием документов
Допустим, документ ссылается на какие-то данные в первоисточнике. И если вдруг эти данные изменились, то человеку, который отвечает за подготовку документов, придётся вручную искать все фрагменты, которые связаны с первоисточником, и заменять устаревшую информацию на новую. А это опять силы и время. Очень сложно поддерживать документы в актуальном состоянии.
Ещё проблематична одновременная работа нескольких человек над большим документом. Сейчас зачастую это много версий одного документа от каждого автора, которые потом мучительно собираются в один большой Word-документ и повторно пересогласовываются.
Эти уязвимости стали отправной точкой при создании собственного продукта.
Скрин создания проекта
Как мы решали эти проблемы в Сфера.Документы?
Вы когда-нибудь крутили калейдоскоп? При смене положения картинка меняется на другую, и всё встаёт на свои места без вашего персонального вмешательства: не нужно пинцетом подгонять кусочки стекла на подходящее место. Такого же эффекта и мы старались добиться в Сфера.Документы, чтобы порядок выстраивался автоматически при внесении любых изменений.
Управление блоками информации: автоматизация и «атомизация»
Нас не устраивал факт работы с документом целиком: при таком подходе сложно управлять его отдельными разделами или фрагментами и всё приходится редактировать вручную. В поисках оптимальной системы управления информацией мы решили, что класс систем, который называется Component CMS (CCMS), — это то, что нужно для работы с объёмными сложно структурированными документами. Они позволяют «рулить контентом» на уровне страниц, абзацев и даже отдельных слов.
Как это работает?
Весь контент документа создаётся из отдельных фрагментов, которые хранятся в едином источнике и вставляются в рабочий документ в виде ссылок, что позволяет автоматически поддерживать согласованность данных во всём документе.
Рассмотрим это на примере. Допустим, в документе есть ссылка на внешний источник информации. Если информация во внешнем источнике изменится, то при создании документа в Word или Confluence специалисту придётся вручную выискивать отличия и менять данные в документе. А при работе в разработанном нами сервисе Cфера.Документы, изменения в документ вносятся автоматически: изменился первоисточник — изменился текст в документе. Такая возможность обновления документов и их отдельных фрагментов в режиме реального времени за счёт интеграции с первоисточниками существенно экономит ресурсы команды.
Кнопка «Показать изменения»
В сервисе есть инструмент, который позволяет подсветить те блоки в тексте, где были внесены редакторские правки. Кнопка «Показать изменения» скрывает неизменившиеся части документа, оставляя для сверки версий только те модули, где есть обновления. Поэтому проверяющему достаточно сличить в среднем четыре-пять страниц документа вместо вычитки сотен страниц в поисках различий их версий.
Готовые шаблоны для заполнения
Оформлять документы в соответствии с ГОСТом или отраслевыми стандартами стало проще. Благодаря готовым шаблонам, связанным с различными типами документов, и подсказкам по их заполнению можно не тратить время на изучение разметки.
Готовая структура, определённые размеры отступов, размеры и расположение заголовков, разметка таблиц, расположение нумерации страниц и сносок — когда все эти параметры изначально уже настроены в соответствии с ГОСТами под задачи пользователя, готовить технические задания, договоры или регламенты становится быстрее и удобнее.
Если в каком-то документе нужна таблица, она будет представлена с количеством столбцов, строк и их названиями в точном соответствии с ГОСТом, без возможности их изменить. У того, кто редактирует документ, просто не будет шансов заполнить их неправильно.
Учитывая факт, что при подготовке технических спецификаций технические писатели переиспользуют половину контента, принцип работы Сфера.Документы в разы повышает их эффективность.
Дополнительные возможности Сфера.Документы
Сервис позволяет импортировать информацию из внешних источников: текст документа формируется автоматически с сохранением ссылок. Возможность импорта из Вики-систем также автоматизирует большой объём работ, которые обычно приходится выполнять вручную.
Благодаря организации контента как сочетания фрагментов, Сфера.Документы позволяет точечно редактировать, согласовывать и проверять «по компонентам» каждую версию документа. Проверяющему не нужно читать весь текст целиком, если ему нужно проверить только таблицу или сопоставить пару определённых абзацев.
За счёт ссылок на первоисточники можно переиспользовать большую часть контента.
Гибкая мультиканальная настройка публикаций позволяет сохранять финальные версии документов в подходящих форматах.
Как работает Сфера.Документы?
Документ, созданный в Сфера.Документы, — это комбинация фрагментов текста. Что-то можно переиспользовать, а что-то писать заново. Образно говоря, это мозаика из кусочков текста, в которой каждый фрагмент может быть удалён, заменён или отредактирован.
Документ, созданный в Сфере
Особенности версионирования
Каждый вариант с правками сохраняется как черновик, причём вносить изменения могут одновременно разные участники команды. Версии черновиков называются в программе документами.
Альтернативные инструменты позволяют делать шаг назад на уровне всего текста документа. В Сфера.Документы реализован механизм отката к предыдущей версии документа на уровне фрагментов, то есть можно вернуть к прежней версии не весь текст целиком, а его отдельные модули. Проще говоря, каждое внесение изменений сохраняется как отдельная версия на уровне фрагментов. Когда получившаяся «мозаика» вас устраивает, можно её «сфотографировать».
Нажимая кнопку «Опубликовать», вы сохраняете ту версию документа, которую на текущий момент считаете финальной: публикация — это чистовик документа.
При этом публикация документа не влияет на возможности его редактирования: эти процессы на платформе разделены. После публикации участники команды по-прежнему могут дорабатывать документ, вносить изменения и согласовывать его до новой финальной точки. Можно опубликовать несколько версий документа и сравнить их. Если понадобится снова внести правки, то документ можно отредактировать и снова опубликовать его чистовик. При работе в Word каждую финальную версию текста нужно сохранять как отдельный документ, в Сфера.Документы такой необходимости нет: и черновики (документы), и чистовики (публикации) хранятся в едином пространстве.
Расширенные возможности комментирования
Сфера.Документы делает процесс сверки версий документов удобным и гибким: когда эксперт проверяет документ, он может оставлять замечания к каждому его фрагменту. Эти комментарии с конкретными предложениями, привязанные к определённым фрагментам («это удалить», «это заменить», «это дополнить тем-то»), помогают эффективнее ориентироваться и редактировать документ. По сути, здесь идёт расширение работы с документом из-под системы электронного документооборота (СЭД). Сейчас в СЭД можно оставлять замечания только на уровне всего документа. А мы переносим работу с замечаниями на уровень отдельного фрагмента, что удобно как автору, так и согласующему при повторной проверке.
Проверяющему удобно сопоставлять тексты на уровне фрагментов, чтобы увидеть, где, когда, кем и какие изменения внесены.
Если сравнивать с работой в Word, то там пользователь может удалить комментарий или случайно стереть слово, к которому он привязан, и комментарий потеряется. Если же замечания оставляются на уровне всего документа, то возникают сложности с поиском элементов, к которым они относятся: найти фрагменты, требующие внимания, становится трудоёмкой задачей. Сфера.Документы решает вопрос с максимально прицельным комментированием и редактированием версий.
Переход из Confluence и Word в Сфера.Документы
Перейти из прежней системы в наш сервис не сложно. Тот беспорядок с данными, который может царить в Confluence и Word, Сфера.Документы умеет автоматически структурировать в единую упорядоченную систему. Платформа обеспечивает импорт большей части плагинов. Импорт из Confluence можно рассматривать как переход от неупорядоченной информации (Confluence — это просто страницы) к её структурности и более манёвренному управлению её компонентами: в процессе переезда происходит мэппинг страниц с их разбивкой и организацией в строго структурированный документ.
Итак, инструменты, которые предлагает Сфера.Документы, позволяют:
Быстро форматировать документы под разные требования.
Благодаря шаблонам меньше времени тратить на поиск информации для подготовки документа и формата его разделов (таблица, схема, текст, список, подразделы и так далее).
Легко делать проверку и согласовывать изменения в документах.
Проще согласовывать информацию в документах и не допускать ошибок (благодаря ссылкам на первоисточники).
