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

Рисунок 13. Окно добавления документа



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

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

Таблица 3. Реализация потребностей пользователей в старом и новом процессе сборки

№	Job Story	Имеющаяся реализация	Новая реализация
1.1	Когда в день релиза нужно быстро опубликовать все документы к новым версиям нескольких продуктов Я хочу быстро найти нужную мне текущую версию продукта и документ, собрать и опубликовать его	Ручной поиск в системе контроля версий, локальная сборка, ручная публикация	Быстрый поиск по фильтрам и поисковой строке, автоматическая сборка на дистанционном агенте и автоматическая публикация
1.2	Когда нужно опубликовать pdf-документы на основе только что доделанного проекта Я хочу одной командой запустить сборку docx, его форматирование и конвертацию в pdf-файл	Локальная сборка, ручное форматирование docx-документа и конвертация в файл pdf	Дистанционная сборка по команде из интерфейса, автоматическое форматирование и конвертация на удалённом компьютере
1.3	Когда у кого-то из коллег ломается локальная сборка из-за ошибки в скрипте Я хочу чтобы скрипты автоматизации были едиными для всех и находились вне доступа моих коллег	Скрипты скачиваются на локальные компьютеры и могут различаться	Единый скрипт хранится удалённо и используется для сборки любого документа
2.1	Когда нужно опубликовать документ моего коллеги, который сейчас в отпуске Я хочу собрать документы из последней версии его проекта удалённо и опубликовать его	Скачивание проекта из системы контроля версий, ручная настройка и проверка параметров сборки, локальная сборка, ручная публикация	Запуск сборки и публикации из интерфейса без необходимости скачивать файлы на локальный компьютер и что-либо менять
2.2	Когда в команду пришёл новый сотрудник, не знакомый с нашими процессами сборки Я хочу чтобы он быстро понял и освоил процесс сборки самостоятельно	Длительное изучение процесса сборки и настройки необходимых программ, вспомогательные статьи и записи, наблюдение за первыми попытками сборки и публикации	Освоение работы с системой контроля версий, а также интерфейса и предоставляемых им возможностей без необходимости дополнительных настроек.
2.3	Когда мне дали проект ушедшего сотрудника Я хочу собрать документ и посмотреть его без дополнительных приготовлений и настраивания инфраструктуры	Ручная настройка и проверка параметров сборки, локальная сборка, ручная публикация	Запуск сборки и публикации из интерфейса без необходимости что-либо менять и перепроверять
3.1	Когда меняется корпоративное оформление документации и нужно поменять шаблоны Я хочу чтобы при изменениях шаблонов или базы данных мои изменения затрагивали все документы и все новые сборки сразу	Замена шаблонов необходима на всех локальных компьютерах с последующей пересборкой документов - нужно оповестить коллег, чтобы они скачали новые версии и обновили документы	Замена шаблонов затронет все новые сборки, запущенные из интерфейса. Коллегам не нужно ничего скачивать, а запустить сборку документов с новым шаблоном может любой свободный писатель
4.1	Когда изменился состав продуктов и нужно отредактировать базу документов Я хочу чтобы доступ к редактированию базы был только у меня и у руководителей команд	Любой писатель может скачать базу из системы контроля версий и внести в неё изменения, если посчитает нужным	Доступ к редактированию свойств документов есть только у некоторых пользователей и утверждается менеджером команды
4.2	Когда нужно добавить в базу данных новый продукт и документы к нему И я не знаю разметки XML Я хочу вписать название продукта и документов без учёта разметки и автоматически перенести их в файл базы данных	Возможно редактирование только XML-файла напрямую и есть риск повредить разметку или внести записи некорректно, после чего нужно будет вычитывать файл на поиск ошибок	Редактирование базы доступно через формы для заполнения, которые конвертируются в формат XML автоматически
5.1	Когда я собираю большой документ и подозреваю, что часть разделов может быть повреждена Я хочу полностью собрать документ «как есть» и увидеть список	Процесс сборки отображается для веб-документов. Сборка документа проходит без сообщений об ошибке, найти ошибку можно только по лог-файлу. В случае ошибки с печатными документами сборка прекращается почти сразу, но ошибку нужно искать самостоятельно.	Процесс сборки отображается для всех типов документов. В конце сборки сервис предоставляет отчёт о результате сборки и числе повреждённых разделов. Ссылка в отчёте ведёт на строки в лог-файле, отражающие повреждённые разделы
5.2	Когда нужно срочно опубликовать большой документ Я хочу в процессе сборки видеть отчёт о том, что в проекте нет повреждений и сборка прошла без ошибок

Как можно видеть, в большинстве случаев существующая реализация осталась практически неизменной, но была вынесена с локальных компьютеров на удалённый агент, а также в рамках архитектуры сервиса подразумевается завершённое автоматическое форматирование для исключения ручного труда писателей. Стоит также отметить, что некоторые Job Stories не были эксплицитно реализованы в рамках данного прототипа. Так, JS 3 из задачи 1 о единстве скриптов сборки и JS 1 из задачи 4 о блокировке доступа к редактированию базы документов не реализованы непосредственно, однако потенциально реализуемы в процессе разворачивания архитектуры и выстраивания работы по новому процессу. Реализация JS 2 из задачи 2 о быстром обучении новых сотрудников может быть проверена только после масштабного тестирования прототипа или его внедрения в отделе.

4.3 Тестирование прототипа

Оценка функциональности прототипа с точки зрения технических писателей была осуществлена с помощью «тестирования первого клика» (first-click testing). Такое тестирование позволяет определить, насколько прототип интуитивно понятен для пользователя, который сталкивается с ним впервые, а также отследить действия пользователей при выборе места клика и впоследствии исправить прототип так, чтобы он соответствовал пользовательским ожиданиям.

Тестирование было проведено на платформе Optimal Workshop (https://www.optimalworkshop.com) и включало в себя три задания, отражающих ключевые потребности пользователей, которые также не покрываются другими решениями по автоматизации документации, и вопросы по окончании тестирования. В тестировании приняли участие 10 технических писателей с уровнем опыта от младшего специалиста до менеджера команды, различным сроком работы в отделе и уровнем технических знаний, что покрывает все типы пользователей сервиса.

Первое задание было посвящено возможной смене формата собираемого документа в секции выбора продукта и последующему переходу на выбор конкретного документа и звучало следующим образом: «You need to generate the printed manual for Backup Agent for Windows latest version». Иллюстрацией к заданию служило изображение основного рабочего экрана, на котором был доступен список продуктов и по умолчанию были выбраны только последние версии и только печатные документы (см. рисунок 14).

Рисунок 14. Иллюстрация к тестовому заданию 1.

В качестве потенциально верных мест первого клика были отмечены тоггл переключения форматов и название продукта, которое открывает доступ к его документам, так как после этого писатель ещё может изменить выбранный по умолчанию формат. 70% (7 из 10) пользователей справились с заданием, при этом 4 пользователей первым местом клика выбрали именно название продукта, а 3 - фильтрующий тоггл. Это можно объяснить тем, что название продукта гораздо сильнее бросается в глаза при быстром просмотре страницы, однако такой выбор тоже позволяет впоследствии правильно собрать документ. Ещё один пользователь выбрал неправильный продукт, один выбрал кнопку сборки, расположенную в другой секции и неактивную на представленном этапе, а один ткнул в пустое место на экране. Подобные ошибки можно объяснить невнимательностью пользователей или случайными кликами.

Второе задание было посвящено смене свойств и тому, поймут ли пользователи разделение свойств продуктов и документов. Оно звучало следующим образом: «Backup Agent for Windows 4.0 is now archive. You need to change settings for this product», и в качестве иллюстрации использовался экран, на котором уже выбран определённый документ названного в задании продукта, и поэтому активны и кнопка редактирования свойств продукта, и кнопка редактирования свойств документа (см. рисунок 15).

Рисунок 15. Иллюстрация к тестовому заданию 2.

Правильным местом первого клика была определена кнопка «Properties» в первой секции, отвечающая за редактирование свойств продукта. 80% (8 из 10) пользователей выбрали именно её местом первого клика, правильно разделив свойства продукта в целом и свойства конкретного выбранного документа. Один из неправильных вариантов был случайным кликом в пустое место экрана, и ещё один - выбором названия документа, хотя оно уже было выбрано.

Третье задание было посвящено работе с ошибками сборки и было направлено на выяснение того, понимают ли пользователи, что итоговый отчёт о сборке может вывести их в лог-файл, указывающий на сломанные разделы, без необходимости искать их самостоятельно. Задание звучало следующим образом: «Your document generation task failed. You want to see what topics you need to fix», а в качестве иллюстрации использовался затемнённый главный экран с выведенным отчётом о неудавшейся сборке (см. рисунок 16).

Рисунок 16. Иллюстрация к тестовому заданию 3.

Правильным местом первого клика была определена ссылка «Errors», ведущая на информацию об ошибках сборки, и 90% (9 из 10) пользователей выбрали именно её. Только один пользователь решил нажать кнопку «ОК», закрывающую окно с отчётом, видимо, чтобы попытаться найти информацию о повреждённых разделах самостоятельно, что также возможно, но займёт больше времени и усилий.

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

На первый вопрос, о разделении выбора документа на два этапа и выносе фильтров на этап выбора продукта, 90% (9 из 10) пользователей выбрали оценки «5» или «4», и только один пользователь оценил функциональность на «3». Схожий результат показал и второй вопрос, о разделении свойств документов и продуктов, однако здесь из 9 положительных оценок 5 составляли «4», хотя в первом вопросе преобладали оценки «5». В тестовом задании не были продемонстрированы сами окна редактирования свойств, поэтому пользователи могли не до конца понять, как разделённый функционал работает, однако эту функцию всё равно оценили положительно. Наиболее высоко же была оценена функциональность отчёта о результатах сборки с возможным переходом на лог-файл: 90% пользователей оценили её на «5», и только один пользователь - на «3», возможно, в связи с тем, что данную функциональность можно и не использовать, если искать повреждённые разделы вручную.

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

В рамках доработки прототипа до более высокой детальности в программе Figma с использованием элементов библиотеки Google Material Design был спроектирован предварительный вариант, отражающий корпоративное цветовое оформление и функциональность прототипа низкой детальности. На макете (см. рисунок 17) представлен главный экран интерфейса, в котором уже выбраны продукт и документ и завершена сборка выбранного документа. В нижней части интерфейса представлен макет взаимодействия с программой сборки с доступом к публикации документа и отчёту сборки.

Рисунок 17. Макет интерфейса высокой детализации

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



ЗАКЛЮЧЕНИЕ

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

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

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

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

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

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

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

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

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



СПИСОК ИСТОЧНИКОВ

1. Buchgeher, Georg, Claus Klammer, Bernhard Dorninger and Albin Kern. “Providing Technical Software Documentation as a Service - An Industrial Experience Report.” 2018 25th Asia-Pacific Software Engineering Conference (APSEC) (2018): 581-590.

2. Buse, Raymond P. L. and Westley Weimer. “Automatic documentation inference for exceptions.” ISSTA '08 (2008).

3. Caponi, Alessandro, Angelo Di Iorio, Fabio Vitali, Paolo Alberti and Marcello Scatб. “Exploiting patterns and templates for technical documentation.” DocEng '18 (2018).

4. Choudhury, Jaya and B. Thushara. “Software Documentation in a Globally Distributed Environment.” 2014 IEEE 9th International Conference on Global Software Engineering (2014): 90-94.

5. Earle, Ralph H., Mark A. Rosso and Kathryn E. Alexander. “User preferences of software documentation genres.” SIGDOC '15 (2015).

6. Gуmez, Abel, Marнa del Carmen Penadйs, Josй H. Canуs, Marcos R. S. Borges and Manuel Llavador. “DPLfw: a framework for variable content document generation.” SPLC '12 (2012).

7. Goodman, Elizabeth, Mike Kuniavsky and Andrea Moed. “Observing the User Experience: A Practitioner's Guide to User Research (Second Edition).” IEEE Transactions on Professional Communication 56 (2013): 260-261.

8. Hardy, Matthew R. B., David F. Brailsford and Peter L. Thomas. “Creating structured PDF files using XML templates.” DocEng '04 (2004).

9. Holtzblatt, Karen and Hugh R. Beyer. “Contextual Design 2nd Edition: Design for Life.” (2017).

I. Scott MacKenzie. “Human-Computer Interaction: An Empirical Research Perspective (2st. ed.).” (2013).

10. Kajko-Mattsson, Mira. “A Survey of Documentation Practice within Corrective Maintenance.” Empirical Software Engineering (2005).

11. Lazar, Jonathan, Jinjuan Feng and Harry Hochheiser. “Research Methods in Human-Computer Interaction.” (2017).

12. Lee, Lilian. “Extended Abstract: Documentation Development Practice in Open Source Startups - Take PingCAP as an Example.” 2019 IEEE International Professional Communication Conference (ProComm) (2019): 255-256.

13. Lehtonen, Miro, Renaud Petit, Oskari Heinonen and Greger Lindйn. “A dynamic user interface for document assembly.” DocEng '02 (2002).

14. Lethbridge, Timothy, Janice Singer and Andrew Forward. “How software engineers use documentation: the state of the practice.” IEEE Software 20 (2003): 35-39.

15. McBurney, Paul W. and Collin McMillan. “Automatic documentation generation via source code summarization of method context.” ICPC 2014 (2014).

16. Meinel, Christoph, Harald Sack and Volker Schillings. “IDDS: an interactive decentralized documentation system.” SIGDOC '01 (2001).

17. Merle, Frйdйric, Aurйlien Bйnel, Guillaume Doyen and Dominique Gaпti. “Decentralized documents authoring system for decentralized teamwork: matching architecture with organizational structure.” GROUP '12 (2012).

18. Moore, Nathan, Kevin Molloy, William Lovo, Sven Mayer, Pawel W. Wozniak and Mj Stewart. “POST: A Machine Learning Based Paper Organization and Scheduling Tool.” Companion of the 2020 ACM International Conference on Supporting Group Work (2020).

19. Moreno, Laura, Gabriele Bavota, Massimiliano Di Penta, Rocco Oliveto, Andrian Marcus and Gerardo Canfora. “Automatic generation of release notes.” FSE 2014 (2014).

20. Novick, David G. and Karen Ward. “What users say they want in documentation.” SIGDOC '06 (2006).

21. Novick, David G. and Karen Ward. “Why don't people read the manual?” SIGDOC '06 (2006).

22. Palmer, James D. and Nakai McAddis. “Documentation as a cross-cutting concern of software.” Proceedings of the 37th ACM International Conference on the Design of Communication (2019).

23. Pawlik, Aleksandra, Judith Segal, Helen Sharp and Marian Petre. “Crowdsourcing Scientific Software Documentation: A Case Study of the NumPy Documentation Project.” Computing in Science & Engineering 17 (2015): 28-36.

24. Penadйs, Marнa del Carmen, Abel Gуmez and Josй H. Canуs. “Deriving document workflows from feature models.” DocEng '12 (2012).

25. Penadйs, Marнa del Carmen, Josй H. Canуs, Marcos R. S. Borges and Manuel Llavador. “Document product lines: variability-driven document generation.” DocEng '10 (2010).

26. Roehm, Tobias, Rebecca Tiarks, Rainer Koschke and Walid Maalej. “How do professional developers comprehend software?” 2012 34th International Conference on Software Engineering (ICSE) (2012): 255-265.

27. Sohan, S. M., Craig Anslow and Frank Maurer. “Automated Example Oriented REST API Documentation at Cisco.” 2017 IEEE/ACM 39th International Conference on Software Engineering: Software Engineering in Practice Track (ICSE-SEIP) (2017): 213-222.

28. Sohan, S. M., Craig Anslow and Frank Maurer. “SpyREST: Automated RESTful API Documentation Using an HTTP Proxy Server (N).” 2015 30th IEEE/ACM International Conference on Automated Software Engineering (ASE) (2015): 271-276.

29. Souza, Sergio Cozzetti B. de, Nicolas Anquetil and Kбthia Marзal de Oliveira. “A study of the documentation essential to software maintenance.” SIGDOC '05 (2005).

30. Stettina, Christoph J. and Werner Heijstek. “Necessary and neglected?: an empirical study of internal documentation in agile software development teams.” SIGDOC '11 (2011).

31. Stock, Ingo and Michael Weber. “Authoring technical documentation using a generic document model.” SIGDOC '06 (2006).

32. Sukale, Ryan and Mark S. Pfaff. “QuoDocs: improving developer engagement in software documentation through gamification.” CHI EA '14 (2014).

33. Vбsquez, Mario Linares, Boyang Li, Christopher Vendome and Denys Poshyvanyk. “How do Developers Document Database Usages in Source Code? (N).” 2015 30th IEEE/ACM International Conference on Automated Software Engineering (ASE) (2015): 36-41.



ПРИЛОЖЕНИЕ

ОСНОВНАЯ ТЕРМИНОЛОГИЯ, ПРИНЯТАЯ В ОТДЕЛЕ ТЕХНИЧЕСКОЙ ДОКУМЕНТАЦИИ

Фидбек - обратная связь от клиентов и других сотрудников;

Релиз - выпуск в продажу продукта или нескольких; день, когда документация по соответствующим продуктам выкладывается на сайт компании;

Док/доки - документ/ы;

Веб-хэлп, веб - документация в формате html;

Пдф - документация в формате pdf;

Ворд - документация в формате docx;

Заливать, перезаливать - публиковать документ; обновлять ранее опубликованный документ;

Гайд - руководство по продукту;

TFS - Team Foundation Server (теперь Azure DevOps Server), система контроля версий;

Юзер гайд - пользовательское руководство;

Чек-аут - check out, извлечение файлов из системы контроля версий для редактирования на компьютере пользователя;

Чек-ин, вчекинить - check in, сохранение сделанных на локальном компьютере изменений в системе контроля версий;

Help&Manual - программа для создания справочных систем; основной инструмент работы писателей;

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

Зум - Zoom Search Engine, движок пользовательского поиска по документации;

Топик - раздел в проекте Help&Manual; соответствующий раздел в готовом документе;

Воркфлоу - процесс работы с документами;

Виртуалка - виртуальная машина;

Фича - функциональность;

CloudBerry Explorer - программа для управления файлами в Amazon S3; используется для публикации веб-документов;

Adobe Experience Manager (AEM) - система управления контентном; используется для публикации печатных документов.

КОНТЕКСТНОЕ ИНТЕРВЬЮ В ПРОЦЕССЕ СБОРКИ ДОКУМЕНТА

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

Писатель: - Привет, да, без проблем. Что именно ты хочешь узнать?

И: - Сначала давай поговорим о сборке и публикации документов, насколько это важный и частый процесс в работе, какое он место занимает в твоей рутине?

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

И: - И много времени это занимает? Как часто ты сталкиваешься с этим процессом?

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

И: - Хорошо, спасибо за информацию. Сейчас мы проведём не традиционное интервью, где я задаю вопросы, а ты даёшь ответы, а так называемое контекстное интервью, то есть ты просто будешь собирать и публиковать документы, как если бы это надо было сделать перед релизом, можно что-то комментировать, а я буду наблюдать и задавать вопросы, если что-то будет непонятно. Здесь главное сам процесс, так что не волнуйся, если что-то не получится или ты что-то забудешь, всё нормально. И тебе надо собрать гайд для агентов, чтобы можно было наблюдать весь процесс сборки. Понятны цели интервью?

П: - Да, понятно всё. Давай тогда сразу начнём, потому что если собирать надо всё, то это может затянуться. Хотя, конечно, гайд по агентам не такой большой, как наш.

[Заходит в учётную запись на компьютере]

П: - Так, чтобы начать работать с гайдом по агентам, надо забрать его из TFS.

[Открывает TFS, раскрывает дерево проектов]

И: - А можешь подробнее рассказать о том, как вы находите нужный проект и как всё организовано здесь?

П: - Ну организовано достаточно просто, вот здесь, в папке Help, находятся все наши документы. Они распределены по продуктам, у каждой папки с продуктом своё название. Вот мы заходим в папку агентов [открывает одну из подпапкок папки Help], видим здесь папки с версиями, от первой до нынешней, четвёртой. Старые версии они архивные, часть из них уже не поддерживается, мы работаем с новой [открывает подпапку «4.0»]. Здесь лежат папки с соответствующими гайдами, они для всех продуктов разные. Мы возьмём обычный юзер гайд [открывает подпапку user]. Здесь уже лежит сам проект и всё, что для него нужно. Так как у меня этой папки не было, её надо забрать себе и сделать чек-аут [запускает команду check-out], чтобы она появилась у меня в соответствующей папке на компьютере, потому что вся работа происходит локально. Конечно, когда собираешь свой проект, это всё у тебя уже есть, ты просто делаешь чек-аут, чтобы можно было вносить в проект изменения.

И: - И все папки с документацией организованы похожим образом?

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

[Открывает другой путь в TFS, забирает последние версии нескольких файлов]

И: - А какие нужны дополнительные файлы?

П: - Ну, вот нужен файл со стилями для пдф-а, его надо положить в папку Help&Manual на диске, потом нужен шаблон для веб-страниц, собственно файл с информацией про все документы, иногда ещё скрипты обновляются. Эти файлы нужны другим программам, поэтому надо правильно настраивать пути, по которым программы будут их искать. У меня когда-то ещё в начале всё пошло не так, поэтому Мёбиус ищет файлы в другой папке. Я сейчас руками их перенесу.

[Копирует файлы из папки, привязанной к TFS, в другие папки]

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

[Запускает генератор веб-страниц и поисковый движок]

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

[Открывает папку с проектом, находит в ней скрипт командной строки Windows]

И: - А что за скрипты?

П: - Их когда-то давно написали, чтобы упростить себе жизнь. Скрипт запускает Мёбиус и Зум, только тут тоже надо сравнить, чтобы все пути были правильные. Особенно с моей странной локальной структурой… [проверяет пути, указанные в скрипте] Да, надо переписать. Потом просто не буду сохранять изменения, чтобы у ребят ничего не сломалось.

[Переписывает пути в скрипте, сверяясь с открытыми папками, проверяет]

[Запускает скрипт, на экране отображается информация о сборке]

И: - А что этот скрипт показывает?

П: - Он показывает, какую программу он сейчас запускает, и он скажет, если не сможет добраться до проекта, например. Но это произойдёт, если ты не сделаешь чек-аут.

[Ждёт завершения сборки, проверяет сообщения в рабочем чате. Проходит около трёх минут]

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

[Переходит в папку генератора сайтов, открывает последний лог-файл, запускает поиск по слову «Error». Поиск показывает 0 результатов]

П: - Вот, ошибок нет, значит, всё нормально. Теперь ещё надо просмотреть его руками, то есть глазами, потому что иногда стили в проекте могут поехать и разные строчки будут разными шрифтами. [Заходит в папку output проекта, открывает первую веб-страницу в браузере] Это некрасиво, и тогда надо в проекте исправлять стили и заново всё собирать. [пролистывает страницы веб-документа] Не смертельно, конечно, но всё равно. Тут на первый взгляд всё нормально…

[Продолжает пролистывать страницы, сканируя строки. Проходит около десяти минут]

П: - Всё проверили, теперь надо закинуть в CloudBerry Explorer, чтобы оно отразилось на сайте с документацией.

[Открывает CloudBerry Explorer, копирует в папку с документами о продукте файлы из папки output, настраивает доступ на чтение]

П: - С вебом закончили, теперь собираем пдф.

[Открывает проект в программе Help&Manual]

И: - У него другой алгоритм работы?

П: - Да, надо настроить задание здесь, потому что Help&Manual даёт возможность собирать ворды из проекта.

[Открывает меню публикации и выбирает задание по сборке docx]

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

[Запускает задание на публикацию, ждёт окончания конвертации]

[Открывает папку output, где теперь есть файл docx. Открывает его]

П: - Так, теперь нам надо прогнать макросы, которые поправят некоторые стилистические вещи, например, таблицы, картинки, шрифты может кое-где.

[Открывает меню макросов Microsoft Word, запускает макрос. Ждёт, пока макрос прогрузится.]

И: - Макросы тоже написаны вами?

П: - Да, кем-то до меня [улыбается]. Но они не всегда работают, некоторые зависают, так что надо быть осторожным. И поэтому надо ещё вручную его перепроверить. В основном чтобы страница не начиналась с картинки, а так часто получается после прямой генерации.

[Проверяет docx файл, отбивая строки перед картинками, чтобы картинки не начинали новый лист]

И: - И много времени это занимает?

П: - Зависит от документа. Для самого большого гайда вроде как несколько дней ребята этим занимаются. Этот гайд меньше, и картинок тут не так много, так что я сейчас справлюсь.

[Продолжает редактировать документ]

П: - О, смотри, стили таблиц слетели [показывает на таблицу, которая стала обычной вместо специальным образом отформатированной]. Такое бывает, это ворд не справляется. Я потом пробегусь заменой.

[Ещё около пятнадцати минут редактирует документ. С помощью поиска находит все таблицы с заголовками Note, Tip, Important и меняет их стиль на необходимый]

П: - Теперь вроде всё. Конвертируем в пдф.

[Открывает меню Adobe Acrobat в Microsoft Word, запускает команду конвертации документа в файл pdf. Компьютер зависает]

И: - А это нормально?

П: - Вообще не очень. У меня просто оперативной памяти мало, наверное, надо ещё заказать. Но на больших гайдах всё может сурово висеть. Лучше в таких случаях больше ничего не открывать, чтобы не дай бог не сделать ещё хуже и вообще всё не сломалось. Так что подождём.

[Смотрит сообщения в телефоне. Конвертация продолжается около семи минут]

П: - Ну ещё не так плохо, большие гайды по полчаса могут конвертироваться. Сейчас посмотрим…

[Открывает документ в формате pdf, сохранённый в той же папке. Пролистывает его за две минуты]

П: - В пдф-ках обычно всё нормально, если и в ворде нормально. Теперь надо закинуть его в АЕМ и там быстро опубликовать.

[Открывает в браузере Adobe Experience Manager, заходит в систему]

И: - Здесь расположены все документы?

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

[Переносит готовый pdf-документ в окно браузера и обновляет. Проверяет заполненные формы свойств и нажимает «Быстрая публикация»]

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

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

П: - Да, в общем всё верно, меня научили делать так.

И: - А можешь немного рассказать о себе, давно ли ты в компании, чем занимаешься?

П: - Я младший технический писатель, здесь работаю полгода. Вообще пишу документацию по ресту [REST API] и помогаю с некоторыми большими документами. Но один релиз уже застала, так сказать, прошла боевое крещение.

И: - А раньше ты занималась технической документацией?

П: - Нет, даже не вникала сильно. Но сейчас мне нравится то, что я делаю, это довольно интересно.

И: - Понятно. Спасибо тебе за участие, успехов в работе и хорошего дня!

П: - Спасибо, тебе тоже!

ИНТЕРВЬЮ СО СТАРШИМИ ТЕХНИЧЕСКИМИ ПИСАТЕЛЯМИ

Интервьюер: - Привет! Я сейчас работаю над новым сервисом, чтобы можно было собирать документы автоматически, и мне хотелось бы поговорить с вами о текущем процессе сборки, его плюсах и минусах и о том, чего ему, возможно, не хватает.

Писатель 1: - Масштабная тема.

Писатель 2: - Да, мы уже давно над этим думаем.

И: - Тогда я задам вам тему, о которой хочу больше узнать, а вы уже будете говорить и, возможно, обсуждать между собой. Так как вы хорошо разбираетесь в происходящем, я не буду ограничивать вас какими-то строгими вопросами. Мы с Алёной [младший технический писатель, участвовавший в контекстном интервью] уже рассмотрели сам процесс сборки, так что общий контекст ситуации мне известен. Хотелось бы от вас подробнее узнать про проблемы, которые возникают в процессе сборки и как вы с ними справляетесь.

П1: - Самая большая проблема - в людях. То есть, им сложно разобраться в нашем воркфлоу, особенно если это совсем новички, они путаются и очень медленно всё делают.

П2: - К тому же есть моральное давление, что вот, ты сейчас выложишь неполный документ или выложишь его не туда, всё сломаешь, и все клиенты сразу же это увидят, посыпется фидбек и тебя уволят.

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

П2: - И ты бегаешь и исправляешь.

П1: - Да, хотя тебе ещё свои доки выкладывать.

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

П1: - Иногда оно их добавляет. Как тогда, с «эс»-ками.

П2: - Да, у нас был один хрестоматийный случай, когда один из коллег редактировал скрипт сборки, не помню уже зачем, и в итоге скрипт у него перестал запускаться. Вроде всё проверили - всё правильно, а не работает. Мне кажется, мы всем отделом в нём день или два копались, не могли понять, что не так. Оказалось, у него вместо английской буквы «си» была написана русская «эс». И вот как такую ошибку отследить? А в идеальном процессе человек вообще не должен этих скриптов касаться, вот как написали их один раз, такими пусть и будут. И поддерживать так гораздо проще было бы.

П1: - Касательно особенностей локальной сборки, вот у [писателя, участвовавшего в контекстном интервью] возникла такая проблема, что ей пришлось переносить взятые из TFS файлы ещё дополнительно, потому что пути настроены неправильно…

П2: - [кивает] Да, такое тоже случается, тоже довольно редко…

П1: - Да, но от таких ошибок тоже никто не застрахован. Я уже и не помню, как так вышло и вообще не представляю, как теперь поправить, это, наверное, всё сносить надо и заново настраивать.

И: - Вообще проблемы на этапе обновления файлов часто происходят? Или больше на этапе самой сборки?

П2: - Проблемы разные. Если смотреть на «препроцессинг», так сказать, на подготовку, то тут главная проблема в человеческом факторе. Где-то не проверил, где-то опечатался, забыл взять последнюю версию файла из TFS - и всё, надо всё переделывать, потому что всё сломалось, и ещё поди найди, где ты там ошибся. То есть надо всё по пунктам заново перепроверять. Вообще ребята часто забывают именно файл с доками обновить, хотя я регулярно пишу об этом. Недавно ещё шаблоны корпоративные поменялись, тоже всем пришлось кучу писем прислать, чтобы обновили.

П1: - С шаблонами у нас была другая весёлая песня, как раз когда ты шаблоны обновил последний раз, у [младшего технического писателя] при конвертации в пдф весь текст пошёл курсивом. Вообще весь! В ворде всё нормально было, мы тоже голову ломали, что могло пойти не так. В общем снесли просто все шрифты, которые используются в наших доках, и поставили заново без курсива. Вроде заработало. Но тоже была довольно интересная ситуация, а пдф-ы собрать - это отдельный гемор сам по себе.

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

П1: - Такая трата рабочих часов [смеётся].

П2: - Кроме шуток, это час твоей работы, который улетает на процесс, в котором ты даже не участвуешь! Так, конечно, не должно быть.

И: - А ещё какие-то проблемы случаются? Что-то, что может обнаружиться после релиза, как все боятся?

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

П2: - Хотя проверять логи и до этого было хорошим тоном. Но всё равно человек может об этом и забыть, особенно если торопится. Логи к тому же лежат в другом месте, это надо пойти, посмотреть, поиском пройтись. Очень много действий.

П1: - Так про весь воркфлоу можно сказать: слишком много действий! Надо меньше.

П2: - Согласен.

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

П1: - Меньше действий! Чтобы не надо было лезть в стопятьсот разных мест, что-то куда-то носить, что-то где-то переименовывать.

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

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

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

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

П2: - Да, к слову об однообразии. Конечно, если перенести всю сборку с локальных наших машинок, то это избавит от проблемы «забыл обновить шаблон» или там «опечатался в скрипте», но есть ещё файл с конфигом, то есть база всех наших доков. Его сейчас может редактировать любой человек, а это файл в формате XML и у него довольно специфическая организация внутренняя…

П1: - Там чёрт ногу сломит.

П2: - Ну это грубо говоря [улыбается]. Но да, кто-то, кто не разбирается в этом, может повредить файл, и это сломает сборку у всех. Поэтому базу тоже надо куда-то прятать, возможно, чтобы её можно было удалённо редактировать, и чтобы этим мог заниматься только я и, например, [менеджер команды и один из старших писателей]. «Защита от дурака», так сказать.

П1: - Кстати, то, что мы можем видеть процесс сборки, особенно сборки хэлпа - какая там прога [программа] запускается, что вообще происходит, ну и потом посмотреть логи на наличие ошибок - это полезная очень фича, её тоже надо оставить.

П2: - Да, возможно, логи надо вынести как-то поближе, потому что без них зачастую сложно понять, как хорошо прошла сборка и ничего ли не сломалось. Хорошее замечание. А так вроде всё сказали?

П1: - Мне кажется, всё основное, да. По крайней мере, в голову ничего больше не приходит.

И: - Хорошо, спасибо за такую подробную информацию. А теперь можете немного рассказать о себе: как давно вы в компании, чем занимаетесь?

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

П1: - Да, пара недель разницы по приходу была. Мы оба старшие технические писатели. Я веду два проекта, и у меня команда из двух ещё ребят, которые здесь не так давно.

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

И: - Понятно, спасибо ещё раз за ваши ответы и хорошего дня!

П1: - Всегда пожалуйста!

П2: - Да, обращайся, если что-то понадобится!

Размещено на Allbest.ru

...