Проектирование веб-приложения для генерирования и публикации документов

В ходе проведения неструктурированных интервью использовались открытые вопросы следующих типов:

Какие проблемы возникают при сборке документации? На каких этапах? Как с ними справляются?

Какие есть преимущества у текущего процесса сборки документации, которые хотелось бы сохранить в новом сервисе?

Какими, на ваш взгляд, должны быть основные функции нового сервиса?

Протокол интервью содержится в Приложении 3.

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

В данной главе мы разобрали основные методики для получения данных от пользователей в рамках подхода Contextual Design. В главе 3 обсуждаются результаты проведённых интервью и наблюдения и полученная из них информация о текущем состоянии процесса сборки документов и задачах сервиса. В главе 4 описывается структура прототипа сервиса и результаты его тестирования целевыми пользователями.



ГЛАВА 3. ОПРЕДЕЛЕНИЕ КОНТЕКСТА И ЗАДАЧ СЕРВИСА

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

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

3.1 Анализ существующей организации работы с документацией

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

Хранение документов и управление базой документации

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

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

Хранение документов организовано в системе управления версиями (и, соответственно, на локальных компьютерах сотрудников) следующим образом: каждый продукт помещён в отдельной папке под кодовым именем, внутри находятся папки с версиями (как актуальными, так и уже устаревшими, т.н. «архивными»), каждая папка версии продукта содержит папки документов для этого продукта. В папке с одним руководством находится проект документа, а также все дополнительные файлы: иллюстрации, диаграммы, скрипты локальной сборки и другие файлы, автоматически создаваемые программой Help&Manual. Кроме того, на локальном компьютере хранится также папка с собранными локально документами, используемыми для проверки корректности сборки (она не загружается в систему контроля версий). Рисунок 1 показывает схему организации документов в системе управления версиями.

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

Рисунок 1. Схема организации документов в системе управления версиями

Так как сборка опирается на конфигурационный файл, в котором содержится вся информация о документах, этот файл необходимо поддерживать актуальным с каждым выпуском новой версии какого-либо из продуктов. Чтобы конфигурационный файл сохранялся актуальным, при появлении нового продукта или новой версии уже существующего один из отвечающих за этот продукт писателей вносит новые данные по продукту и сопутствующим документам, а затем обновляет файл в системе управления версиями, откуда его должны будут забрать все остальные. К вносимым данным, помимо названия и версии продукта и имени документа, относятся его описание, тип, URL на сайте с документацией, путь к папке в системе управления версиями и условия сборки, использующиеся в программе Help&Manual. На рисунке 2 показан отрывок конфигурационного файла со всеми свойствами, указываемыми для документа.



Рисунок 2. Конфигурация документа

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

Разработка документации начинается с проекта в программе Help&Manual, который редактируется и дополняется писателями в соответствии с процессом разработки самого продукта с сохранением изменений в системе управления версиями. Когда наступает время публикации документов, писателю нужно сначала внести изменения в конфигурационный файл (или попросить более опытных коллег это сделать), добавив туда новый продукт и/или его документы. Затем он забирает из системы управления версиями файлы корпоративных стилей и шаблонов сборки, конфигурационный файл с базой документов и сам проект. Дальнейшие действия слегка различаются в зависимости от формата собираемого документа, но для большинства документов необходима сборка в обоих форматах

Для создания печатной документации нужно настроить задание по сборке, предлагаемое в Help&Manual, прописав в нём пути к файлу проекта и файлу с корпоративным шаблоном, а также настроив свойства будущего документа. После запуска задания программа возвращает файл в формате DOCX, в котором писатель запускает макросы Microsoft Word для проверки соответствия текста стилистическим руководствам. После этого весь документ проверяется вручную, что для больших файлов может занимать день или несколько. Это делается для исправления стилистических ошибок, которые не охватываются макросами. Затем файл конвертируется в формат PDF и может быть проверен повторно. Готовый PDF-файл загружается писателем в Adobe Experience Manager и публикуется оттуда.

Для создания веб-документации используется не внутреннее задание программы Help&Manual, а отдельный генератор веб-страниц. Для работы с ним настраивается сначала сама программа, затем скрипты сборки, получаемые из системы управления версиями. После запуска скрипта и окончания сборки писатель проверяет результат, просматривая лог-файлы генератора на наличие ошибок, а также просматривая собранные веб-страницы на локальном компьютере для проверки стилистической правильности сборки. Если всё собралось верно, полученные веб-страницы вместе с дополнительными файлами вручную загружаются в CloudBerry Explorer для публикации. Рисунок 3 показывает диаграмму общего процесса сборки и публикации документов. Как показало контекстное интервью, наибольшие трудности в процессе сборки вызывают те этапы, где требуется напряжение внимания, а именно проверка соответствия параметров сборки полноты собранного документа, что влияет на успешность всех последующих действий. Самыми длительными являются этапы ручного форматирования печатного документа, его конвертации в PDF файл, а также ручной проверки веб-документации через браузер пользователя. У проводившего сборку писателя также возникла проблема с размещением полученных из системы управления версиями файлов стилей и конфигурационного файла: их пришлось дополнительно перемещать в папки, отличные от места загрузки. Как объяснил писатель, такая проблема возникла из-за того, что на локальном компьютере изначально были неправильно настроены пути, по которым различные используемые программы ищут нужные файлы, и ему приходится после скачивания из системы управления версиями вручную перебрасывать файлы в нужные места, а затем менять пути в скриптах сборки, что оставляет дополнительное место для ошибок. Эта и другие возможные проблемы также поднимались опытными техническими писателями в ходе интервью.

Рисунок 3. Диаграмма текущего процесса сборки документов.

Проблемы и преимущества существующего процесса

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

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

Так, для более автоматизированной сборки документов техническими писателями были написаны скрипты на языке PowerShell, которые получали на вход проект документа из программы Help&Manual и запускали генератор веб-страниц для конвертации проектных файлов в набор html-страниц. Эти скрипты опираются на то, где на локальном компьютере писателя расположены все необходимые файлы и программы: проект документа, база данных документов, корпоративные шаблоны, исполняемые файлы генератора веб-страниц и программы для поддержки поиска по страницам.

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

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

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

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

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

Несмотря на все недостатки, существующий паттерн сборки выполняет свою основную задачу: позволяет техническим писателям собирать документы разных форматов из проектов Help&Manual, а использование скриптов и макросов Microsoft Word позволяет добавить в них элементы автоматического тестирования и форматирования. При запуске скрипта сборки писатель также может видеть прогресс сборки в реальном времени, включая информацию о том, какую программу запускает скрипт. Все эти функции писателям хотелось бы сохранить в новом сервисе.

3.2 Выделение потребностей пользователей

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

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

Для отображения основных задач, стоящих перед пользователями, были составлены следующие Job Stories:

Задача 1. Сборка и публикация документов

Job Story 1

Когда в день релиза нужно быстро опубликовать все документы к новым версиям нескольких продуктов

Я хочу быстро найти нужную мне текущую версию продукта и документ, собрать и опубликовать его

Чтобы выложить документы вовремя и не тратить время и нервы на многоступенчатую сборку и исправление возникших ошибок

Job Story 2

Когда нужно опубликовать pdf-документы на основе только что доделанного проекта

Я хочу одной командой запустить сборку docx, его форматирование и конвертацию в pdf-файл

Чтобы не тратить время на форматирование вручную, не рисковать зависанием компьютера, не совершать ошибок из-за торопливости и опубликовать документ в нужном формате вовремя

Job Story 3

Когда у кого-то из коллег ломается локальная сборка из-за ошибки в скрипте

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

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

Задача 2. Сборка и публикация чужих документов

Job Story 1

Когда нужно опубликовать документ моего коллеги, который сейчас в отпуске

Я хочу собрать документы из последней версии его проекта удалённо и опубликовать его

Чтобы не скачивать весь проект себе, не разбираться в его скриптах и не переписывать их для себя, что займёт время и усилия

Job Story 2

Когда в команду пришёл новый сотрудник, не знакомый с нашими процессами сборки

Я хочу чтобы он быстро понял и освоил процесс сборки самостоятельно

Чтобы не тратить время на долгие объяснения и исправление его ошибок и сразу погрузить его в работу над проектом

Job Story 3

Когда мне дали проект ушедшего сотрудника

Я хочу собрать документ и посмотреть его без дополнительных приготовлений и настраивания инфраструктуры

Чтобы быстро влиться в работу над собственно проектом и не тратить время на лишние действия и перестройку своей инфраструктуры либо переписывание скриптов сборки

Задача 3. Обновление шаблонов и базы документации

Job Story 1

Когда меняется корпоративное оформление веб- и печатной документации и нужно поменять шаблоны

Я хочу чтобы при изменениях шаблонов или базы данных мои изменения затрагивали все документы и все новые сборки сразу

Чтобы не перепроверять сборки документов и не напоминать коллегам, что они должны обновить файлы на своих компьютерах

Задача 4. Управление базой документации

Job Story 1

Когда изменился состав продуктов и нужно отредактировать базу документов

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

Чтобы младшие технические писатели не могли по ошибке изменить базу данных, и чтобы я был уверен, что редактированием базы занимаются только опытные сотрудники

Job Story 2

Когда нужно добавить в базу данных новый продукт и документы к нему

И я не знаю разметки XML

Я хочу вписать название продукта и документов без учёта разметки и автоматически перенести их в файл базы данных

Чтобы не запутаться в разметке xml-файла и не сломать сборку по ошибке

Задача 5. Отображение логов и прогресса сборки документации

Job Story 1

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

Я хочу полностью собрать документ «как есть» и увидеть список повреждённых разделов

Чтобы не пересобирать документ несколько раз для исправления каждого повреждённого раздела

Job Story 2

Когда нужно срочно опубликовать большой документ

Я хочу в процессе сборки видеть отчёт о том, что в проекте нет повреждений и сборка прошла без ошибок

Чтобы быть уверенным, что не опубликую неполный документ, и потом не проверять его вручную

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

JS	Контекст	Потребность	Мотивация	Частота	Влияние на работу
1.1	Нужно быстро опубликовать много обновлённых документов в нескольких форматах.	Быстро найти нужную версию продукта и опубликовать его	Чтобы не тратить время на сборку, ручное форматирование и проверку, не совершать ошибок по торопливости и опубликовать документы вовремя	Часто	Среднее
1.2		Быстро запустить автоматическую сборку и форматирование		Иногда	Сильное
1.3	У кого-либо из писателей сломалась локальная сборка и он не может опубликовать документы вовремя	Общие скрипты сборки, которые нельзя изменить на локальном компьютере	Чтобы другие не допускали ошибок при редактировани и мне не приходилось тратить время на их исправлении и настройке	Редко	Сильное
2.1	Надо быстро опубликовать документ, над которым я никогда не работал	Собрать и опубликовать нужный документ удалённо, ничего не скачивая себе.	Не тратить время на проверку скриптов и настройку сборки, не засорять локальный диск дополнительным проектом	Редко	Сильное
2.2	В команду пришёл новый сотрудник, который ничего не знает о нашем процессе работы	Быстрая адаптация сотрудника в процессе работы и привлечение его к сборке документов	Не тратить время и усилия на долгие объяснения и наблюдение за новеньким в процессе сборки, сразу поручить ему проект	Редко	Сильное
2.3	Я получил в работу проект ушедшего сотрудника	Сразу начать собирать и публиковать документы	Не тратить время на перенастройку сборки под локальную инфраструктуру и исправление ошибок	Редко	Сильное
3.1	Изменилось оформление корпоративных шаблонов и нужно обновить все документы в соответствии с ними	Чтобы изменения шаблонов автоматически затрагивали все документы	Не проверять документы вручную и не напоминать коллегам об обновлении файлов на компьютерах	Редко	Среднее
4.1	Нужно отредактировать базу документов, так как добавилась версия продукта/новый документ	Чтобы только у меня и моих доверенных лиц был доступ к редактированию базы	Чтобы младшие коллеги по ошибке не изменили базу данных и не помешали работе всей команды	Часто	Сильное
4.2	Нужно отредактировать базу документов, а я не знаю языка XML	Иметь возможность редактировать базу без учёта разметки XML с автоматическим переводом на язык разметки	База содержалась в порядке, и я не запутался в незнакомом языке и не испортил файл по ошибке	Часто	Среднее
5.1	Мне нужно собрать и опубликовать большой документ, часть разделов в нём может быть повреждена, и я не знаю, какие именно	По итогу сборки получить доступ к списку повреждённых разделов	Чтобы не повторять цикл сборки несколько раз при обнаружении нового повреждённого раздела и ошибке сборки, а найти и исправить все повреждённые разделы сразу	Часто	Сильное
5.2		Отслеживать процесс сборки и по итогу сразу видеть, есть ли ошибки сборки	Чтобы без ручной проверки быть уверенным, что опубликую полный документ без повреждённых и пропущенных разделов	Часто	Сильное



Задачи пользователей, частота их встречаемости и влияние на работу писателей.

Выделенные задачи можно свести к четырём ключевым потребностям пользователей, которые возникают наиболее часто и вызывают наибольшие затраты времени и усилий технических писателей:

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

Быстрая сборка документов двух форматов из одного исходного проекта;

Удалённое управление базой документов;

Отображение отчёта сборки и информации о повреждённых разделах.

Также из контекстного интервью и составленных Job Stories можно выделить другие потребности технических писателей в отношении процесса сборки документов. К ним относятся: поддержка работы с XML-файлами программы Help&Manual (основного инструмента работы писателей), связь с системой управления версиями, хранение собранных документов и их передача в инструменты публикации. Кроме того, стоит учитывать, что большая часть пользователей не обладает специализированными знания в области программирования и специализированной разметки. Ниже будут рассмотрены возможные реализации данных потребностей с использованием других существующих инструментов и циклов работы.

3.3 Анализ существующих решений

В главе 1 были рассмотрены распространённые способы автоматизации работы с документацией, включающие в себя объединение нескольких инструментов, иногда с добавлением объединяющего фреймворка или дополнительного пользовательского интерфейса. К основным способам можно отнести следующие: сочетание текстового процессора и файлообменника; Confluence и другие вики-системы; сочетание какого-либо языка разметки (Markdown, XML, DITA и др.) и системы управления версиями (Git, TFS) в соответствии с концепцией Docs as Code; подход Document Product Lines и его вариации; и основанные на данных подходах индивидуальные разработки под конкретный процесс работы (наподобие Buchgeher et al., 2018). Рассмотрим возможность реализации потребностей пользователей, связанных со спецификой процесса работы с документами, данными способами.

1. Язык разметки + система управления версиями

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

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

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

2. Document Product Lines

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

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

3. Confluence и вики-системы

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

4. Текстовый процессор + файлообменник

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

Таблица 2 суммирует данные анализа по реализации существующими инструментами основных потребностей технических писателей.

	Язык разметки + система управления версиями	Document Product Lines	Confluence и вики-системы	Текстовый процессор + файлообменник
Дистанционная сборка	Возможно*	Неизвестно**	Возможно	Возможно
Сборка документов разных форматов	Нужны дополнительные инструменты; не подходит для печатных версий	Доступно, но сборка осуществляется не по документам, а по отдельным разделам	Нужны дополнительные инструменты	Сборка веб-версий затруднительна
Удалённое управление базой документов	Отсутствует	Отсутствует	Отсутствует	Отсутствует
Отчёт и информация о повреждённых разделах	Неизвестно	Неизвестно	Неизвестно	Отсутствует

* - задачу могут решить некоторые инструменты среди используемых в рамках подхода

** - возможность выполнения задачи не была исследована, так как задача не входит в цели подхода

Таблица 2. Реализация потребностей пользователей существующими решениями

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

В данном случае также можно видеть, что существующие подходы к автоматической сборке документации не покрывают ключевых потребностей пользователей: сборку разных форматов из одного источника без использования дополнительных инструментов, а также управление единой базой документов и отслеживание ошибок сборки. Наиболее близким процессом является использование языка разметки в сочетании с системой управления версиями, однако текущий процесс сборки не ограничивается этими двумя инструментами. Подход Document Product Lines покрывает необходимость хранения документов и редактирования свойств, однако он не подразумевает единой базы, и, что важнее, существующий процесс не требует основы DPL - сборки документа из отдельных разделов. Некоторые существующие работы (Lehtonen et al., 2002) также внедряют возможность управления параметрами документа, однако не позиционируют это как ключевую функцию и не акцентируют внимание на этой возможности. Кроме того, новый сервис также должен обладать возможностью переноса сборки на дистанционный агент, что также возможно не со всеми подходами, и поддерживать специализированные инструменты, которые используются техническими писателями. Поэтому представляется наиболее логичным спроектировать новый сервис, который учтёт данные потребности пользователей и особенности существующего процесса.

3.4 Определение функционального наполнения прототипа

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

Сборка документов с автоматической конвертацией и форматированием файлов проекта дистанционно.

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

Быстрый выбор необходимого документа для продукта нужной версии и формата.

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

Визуализация отчётов по результату сборки.

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

Дистанционное редактирование базы данных документов.

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

Закрытие общего доступа к редактированию базы документов.

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

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



ГЛАВА 4. ПРОЕКТИРОВАНИЕ СЕРВИСА ПО АВТОМАТИЧЕСКОЙ СБОРКЕ ДОКУМЕНТАЦИИ

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

Также в данной главе рассмотрен прототип графического веб-интерфейса низкой детализации (Low fidelity prototype), спроектированный для решения ключевых задач пользователей в рамках нового процесса сборки документов, процедура оценки прототипа командой технических писателей и выводы, сделанные по результатам данной оценки.

4.1 Проектирование процесса сборки и публикации документов

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

Редактирование проекта в программе Help&Manual остаётся основной работой технического писателя. Когда эта работа окончена, писатель сохраняет файлы проекта в системе контроля версий и переходит к работе с веб-интерфейсом. В интерфейсе он может отредактировать базу документов, не взаимодействуя с языком разметки напрямую - добавить новые записи или изменяет уже существующие. После выбора формата выходного файла и документа, который нужно собрать, пользователь запускает сборку.

Система запускает сборку на удалённом компьютере, где получает свойства выбранного документа из базы, забирает из системы управления версиями необходимые для сборки выбранного формата файлы и собирает документ. Для сборки печатного формата система начинает задание программы Help&Manual, которая отдаёт неформатированный файл DOCX. Затем система адаптирует его под корпоративные стандарты с помощью вспомогательных макросов, проверяет на соответствие стилистическим требованиям, конвертирует в PDF-файл средствами Adobe Acrobat и загружает в удалённое хранилище. Для сборки веб-документации система запускает генератор сайтов, который возвращает html-страницы с сопутствующими файлами. Эти страницы загружаются на внутренний сайт компании. В процессе сборки система отслеживает лог-файлы собирающих программ: сколько разделов собрано успешно, сколько программа выдала предупреждений и какие разделы были повреждены. Повреждение разделов не оказывает влияния на сборку, но отражается в финальном отчёте.

Пользователь в интерфейсе может наблюдать прогресс сборки, при этом его компьютер никак не задействован и во время сборки больших файлов писатель может заниматься другими задачами. По окончании сборки сервис предоставляет пользователю отчёт об успешности выполнения задачи. Если часть разделов были повреждены, пользователь может просмотреть названия этих разделов и впоследствии исправить их в исходном проекте. Если же сборка прошла успешно, пользователь может как опубликовать документ, отправив команду из интерфейса, так и предварительно прочитать его. Для печатных версий доступно скачивание из удалённого хранилища в форматах DOCX и PDF, для веб-версий - просмотр сайта с документом по внутренней ссылке. При получении команды на публикацию документа система забирает из хранилища PDF файл и загружает его в Adobe Experience Manager, а также копирует файлы веб-версии в CloudBerry Explorer. Пользователь затем может по ссылке из интерфейса выйти на раздел публичного сайта с документацией, соответствующий собранному документу, и проверить успешность публикации. Рисунок 4 показывает диаграмму обновлённого процесса с выделением тех этапов сборки, которые будут происходит на удалённом агенте под руководством сервиса.

Рисунок 4. Диаграмма нового процесса сборки документов



Процесс сборки с использованием сервиса отличается от имеющегося в первую очередь тем, что все действия пользователя сводятся к взаимодействию с интерфейсом в рамках последовательности справа, на рисунке 4 выделенной жёлтым. Все действия, которые раньше выполнялись пользователем вручную, такие как настройка программ и скриптов, получение файлов из системы управления версиями, форматирование и конвертация файлов, вместе с самим процессом сборки перенесены на удалённый агент (на рисунке 4 - область, очерченная фиолетовым). Именно на удалённой машине, без влияния на компьютер пользователя, производятся все ресурсозатратные действия: сборка, форматирование и конвертация файлов, а также, благодаря удалённому хранилищу, отсюда может производиться и непосредственная публикация документов.

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

4.2 Прототипирование интерфейса сервиса по сборке документации

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

Работа с прототипом начинается с главного экрана (см. рисунок 5). Так как сервис по автоматизации будет располагаться на корпоративном веб-портале, доступ к которому есть только с авторизованных компьютеров, было решено не проектировать страницу с вводом логина и пароля, чтобы не заставлять пользователя совершать излишние действия. Таким образом, при открывании веб-страницы сервиса по сборке документации, пользователь сразу увидит рабочий экран, который будет оставаться практически неизменным по мере процесса сборки.

Рисунок 5. Главный экран прототипа

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

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

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

Рисунок 6. Секция с пользовательской информацией

Основную часть крайней правой секции занимает поле со списком всех версий всех имеющихся продуктов компании (см. рисунок 7). Так как общее количество продуктов уже достаточно велико и будет только увеличиваться, для более быстрого поиска и фильтрации были добавлены строка поиска по имени продукта, а также чек-боксы, отвечающие за показ архивных и/или текущих версий продуктов (по умолчанию показываются только текущие версии, как наиболее часто использующиеся). Кроме того, так как за одну сессию можно собрать только один документ одного формата, а также есть продукты, для которых разрабатываются только документы одного формата из двух возможных, был добавлен тоггл переключения между печатными и веб-версиями документов. Этот тоггл влияет на то, какие документы будут отображаться при поиске, а также на функционал второй секции, отвечающей за генерацию документов. По умолчанию тоггл включен на формат веб-документов как наиболее активно меняющихся. Внизу секции расположены кнопки «Add New» и «Properties», открывающие дополнительное окно для добавления нового продукта в базу данных или редактирование существующего.

Рисунок 7. Секция выбора продукта

При выборе какого-либо продукта становится активной вторая секция, отвечающая за выбор документа, запуск его сборки и просмотр результата (см. рисунки 8 и 9). Основную часть секции, так же как и в предыдущей, занимает поле со списком документов для выбранного продукта. При этом отображаются только документы выбранного формата (например, при выборе печатной версии не будет предлагаться сборка REST API reference, для которой выпускают только веб-документацию). В верхней части секции также расположена строка поиска, а в нижней основное место занимает кнопка «Generate» запуска сборки документа. Под ней расположены кнопки «Properties» и «Add new», отвечающие за просмотр и редактирование свойств документа и за добавление нового документа соответственно. В левой нижней части секции расположены ссылки: для печатной версии это ссылки на скачивание собранного документа в формате DOCX и на конвертацию его в формат PDF с последующим скачиванием для ручной загрузки в Amazon S3 Bucket (см. рисунок 8); для веб-версии - ссылки на просмотр последней версии собранного документа на внутреннем сайте технической документации и на просмотр актуальной документации на внешнем сайте компании (см. рисунок 9).

Рисунок 8. Секция выбора документа для веб-версий



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

После запуска сборки документа становится активной нижняя часть интерфейса, отведённая под отображение информации о процессе сборки, которая будет заимствоваться из инструмента TeamCity. Информация о самом процессе и о логах сборки, отображающихся в режиме реального времени, отображается на вкладках «Process» и «Logs» соответственно. На вкладке с прогрессом (см. рисунок 10) показываются получаемая из TeamCity информация о времени запуска задания и приблизительном времени его окончания, а также шкала прогресса с отображением того, какой именно этап сборки происходит в данный момент и сколько этапов осталось пройти. Одновременно с заполнением шкалы прогресса на вкладке с логами отображается получаемый из TeamCity лог-файл с отчётом по процессу в реальном времени.

Рисунок 10. Макет встроенного интерфейса TeamCity



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

Рисунок 11. Макет отчёта об успешной сборке

Для поддержки функции просмотра и редактирования базы документов в секции, отвечающие за выбор продукта и документа были добавлены кнопки «Add New» и «Properties». Первая отвечает за добавление нового продукта или документа в уже существующий продукт (в зависимости от того, на какой вкладке она расположена), вторая - за просмотр и редактирование свойств существующего продукта или документа по аналогии. Эти кнопки вызывают дополнительные окна, которые отображают свойства продуктов и документов из базы данных формата XML в более удобном для пользователя виде формы для заполнения. Для редактирования и добавления вызывается одно и то же окно с формой, разница заключается только в том, что при вызове команды на добавление поля формы пусты, в то время как при вызове команды на редактирование они заполнены данными по соответствующему продукту или документу, полученными из XML-файла.

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

Рисунок 12. Окно добавления продукта

Окно по добавлению/редактированию документа (см. рисунок 13) отображает свойства, индивидуальные для каждой записи о документе в базе данных и необходимые для сборки документов в печатной и веб-версиях. К общим свойствам относятся название документа, его URL адрес, название проекта Help&Manual, из которого собираются документы, и внутренние условия программы Help&Manual, которые могут быть использованы в проекте. Для веб-версий указаны такие дополнительные свойства, как заголовки в разметках HTML и Open Graph, а для печатных документов - название, заголовок и тип документа.

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

...