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

Размещено на http://www.allbest.ru/

ФЕДЕРАЛЬНОЕ ГОСУДАРСТВЕННОЕ АВТОНОМНОЕ ОБРАЗОВАТЕЛЬНОЕ УЧРЕЖДЕНИЕ

ВЫСШЕГО ПРОФЕССИОНАЛЬНОГО ОБРАЗОВАНИЯ

«НАЦИОНАЛЬНЫЙ ИССЛЕДОВАТЕЛЬСКИЙ УНИВЕРСИТЕТ

«ВЫСШАЯ ШКОЛА ЭКОНОМИКИ»

Факультет Санкт-Петербургская школа физико-математических и компьютерных наук

Выпускная квалификационная работа

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

Шакирова Карина Александровна

Санкт-Петербург 2020



СОДЕРЖАНИЕ

ВВЕДЕНИЕ

ГЛАВА 1. АНАЛИЗ ПОДХОДОВ К НАПИСАНИЮ И АВТОМАТИЗАЦИИ ТЕХНИЧЕСКОЙ ДОКУМЕНТАЦИИ

1.1 Коллаборативное создание документов

1.2 Восприятие документации

1.3 Автоматизация документации

ГЛАВА 2. ОПРЕДЕЛЕНИЕ ДИЗАЙН-ФРЕЙМВОРКА И МЕТОДОВ ИССЛЕДОВАНИЯ

2.1 Contextual design

2.2 Контекстное интервью в процессе генерации документов

2.3 Интервью с техническими писателями

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

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

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

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

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

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

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

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

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

ЗАКЛЮЧЕНИЕ

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

ПРИЛОЖЕНИЕ



ВВЕДЕНИЕ

Активно развивающийся рынок программного обеспечения делает всё более актуальной задачу быстрого создания подробной технической документации для регулярно обновляющихся программ. При этом, несмотря на развитие различных видов вспомогательных материалов (видео-туториалы, форумы и др.), техническая документация от производителя остаётся наиболее востребованной среди конечных пользователей (Earle et al., 2015, Novick & Ward, 2006) и разработчиков (Lethbridge et al., 2003). Как основной источник информации о продуктах, техническая документация продолжает активно изучаться в сферах разработки программного обеспечения и управления знаниями (по Buchgeher et al., 2018).

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

Чаще всего в процессе работы над каждым документом техническим писателям приходится взаимодействовать со множеством программ. Это и программы, в которых создаётся проект документа, и инструменты сборки для разных выходных форматов, и программы вёрстки документа в соответствии с корпоративными стандартами. Такой многоступенчатый процесс регулярно занимает длительное время и усилия, а также требует освоения большого количества программ и неустойчив к человеческим ошибкам. Эти проблемы обусловливают основные недостатки технической документации: неполную и устаревшую информацию (Lethbridge et al., 2003), а пользователи отмечают и другие недостатки, связанные с нахождением нужной информации и навигацией по документу (Novick & Ward, 2006). Поэтому уже долгое время предпринимаются попытки автоматизировать написание документации, улучшить получаемые документы и упростить работу технических писателей.

Одним из основных подходов стало групповое создание документации (Pawlik, A. & Segal, J., 2015). Оно позволило перенести часть работы технических писателей на пользователей и разработчиков, которые также разбираются в продукте. Несмотря на её очевидное удобство для расширения сообщества и получения обратной связи от непосредственных пользователей, такая система подходит далеко не всем компаниям и не может использоваться при создании печатных пользовательских руководств. Похожим недостатком обладает и активно развивающаяся концепция Docs as Code, позволяющая техническим писателям пользоваться теми же инструментами и паттернами работы, которые используют разработчики при работе над кодом продукта, и созданная изначально для написания документации к библиотекам и исходному коду программ.

Для автоматизации сборки не только веб-документации, но и печатных руководств чаще всего используются индивидуальные решения, создаваемые под конкретный процесс работы и используемые командой инструменты (Gуmez et al., 2012, Lehtonen et al., 2002). Некоторые из них адаптируют или дополняют известные подходы и сочетания инструментов, такие как система контроля версий и языки разметки, вики-сайты и Confluence, текстовые процессоры и файлообменники. Одним из часто использующихся подходов стал Document Product Lines, позволяющий дробить документы на множество разделов и уже в процессе сборки определять, какие именно разделы должны попадать в конкретный документ, и собирать уникальные документы под текущий запрос пользователя (Penadйs et al., 2010).

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

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

Поставленная цель определила следующие задачи:

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

обосновать выбранный дизайн-фреймворк и соответствующие ему методы исследования;

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

определить основные потребности будущих пользователей сервиса;

проанализировать реализацию потребностей пользователей с использованием существующих решений;

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

спроектировать прототип сервиса;

протестировать прототип с участием пользователей.

При выполнении работы использовались следующие методы в рамках подхода Contextual Design:

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

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

составление Job Stories, содержащих основные задачи сервиса;

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

дизайн прототипа с минимально необходимым функционалом;

тестирование прототипа целевыми пользователями.

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

Применение подхода Contextual Design для прототипирования в сфере технической документации;

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

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

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

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

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

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

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

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

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



ГЛАВА 1. АНАЛИЗ ПОДХОДОВ К НАПИСАНИЮ И АВТОМАТИЗАЦИИ ТЕХНИЧЕСКОЙ ДОКУМЕНТАЦИИ

Данная работа направлена на создание прототипа, который сделает более удобным для пользователей создание технической документации. Следовательно, необходимо более подробно осветить существующие теоретические работы в области взаимодействия с документацией, а также эмпирические решения, направленные на автоматизацию работы технических писателей. Ниже подробно рассмотрены следующие аспекты данного вопроса: совместная работа над общими документами и децентрализованное создание документов; автоматизированное создания документации для программного обеспечения на основе исходного кода; отношение разработчиков программ и пользователей к технической документации и предъявляемые к документам требования; автоматизация сборки традиционных документов в печатном и веб-формате. Также были изучены некоторые эмпирические работы, направленные на упрощение создания документов для самих технических писателей (Buchgeher et al., 2018, Gуmez et al., 2012, Lehtonen et al., 2002).

1.1 Коллаборативное создание документов

Большое количество появляющихся и обновляющихся программных продуктов делает документацию, также регулярно обновляющуюся и понятную для конечного пользователя, необходимой частью любого программного обеспечения. Некоторые исследователи соглашаются, что лучшим автором документации для программного обеспечения являются сами создатели программы - программисты и/или учёные, создавшие тот или иной инструмент или написавшие код библиотеки (Meinel, Sack, Schillings, 2002). Однако по различным причинам разработчики программ редко сами принимаются за написание технической документации к своему продукту (подробнее об отношении программистов и учёных к написанию документации см пункт 1.2 данной работы).

Организация работы над документацией

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

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

Перед организаторами написания документации через краудсорсинг стоит большое число возможных проблем, с которыми, в частности столкнулись создатели проекта документации библиотеки NumPy (Pawlik, A. & Segal, J., 2015). К ним относятся правильно настроенная инфраструктура, которая позволит многим пользователям редактировать документацию, но при этом сохранит возможность модерирования и привязку документации к исходному коду библиотеки; соблюдение всеми членами сообщества единой стилистики в написании документации; длительное мотивирование и организация как уже состоящих в сообществе пользователей, так и новичков.

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

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

Инструменты совместной работы над документацией

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

Так, бесплатный и широко распространённый Git или патентованный и более многозадачный Azure DevOps Server (ранее известный как Team Foundation Server) позволяют каждому члену команды работать в собственном локальном репозитории и затем распространять сделанные изменения на репозитории других участников. Другие системы управления версиями, такие как бесплатный Apache Subversion или TeamCity от JetBrains, распространяемый по модели freemium, предоставляют команде разработчиков единое хранилище, локальные копии которого хранятся на компьютерах членов команды.

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

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

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

Недостаточность традиционных средств написания документации зачастую приводит к тому, что в каждом отдельном случае разработчики используют несколько инструментов или модифицируют существующие программы под свои нужды. Так, в случае с оффлайн текстовыми процессорами, такими как Microsoft Word, для обеспечения обмена информацией между членами команды сам текстовый процессор необходимо дополнять средством для хранения и передачи файлов. В качестве такого инструмента могут служить файлообменники, приспособленные для синхронизации папок и файлов на нескольких компьютерах, такие как Google Drive или Dropbox.

Системы управления версиями могут дополняться удобными для пользователя интерфейсами и фреймворками для автоматизированной синхронизации, основанными на специфике работы внутри команды (Merle, Frйdйric & Bйnel, 2012). Для более разнообразной интеграции с различными текстовыми редакторами, системами управления версий и даже вики-сайтами разработчики могут создавать собственные программы, которые переводят комментарии в коде в структурированную автоматически собираемую документацию (Palmer, James & McAddis, Nakai, 2019). В более простом случае, система управления версий может использоваться в совокупности с облегчёнными языками разметки (такими как Markdown или reStructuredText) для дальнейшего создания документации на основе подхода «docs like code».

1.2 Восприятие документации

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

Однако здесь исследователи, проводившие опросы разработчиков и программных инженеров, сталкиваются с противоречием: большинство опрошенных программистов признают важность и необходимость полной, единообразной и актуальной документации, но вместе с тем и программисты, и исследователи отмечают её частый недостаток или полное отсутствие (Kajko-Mattsson, 2005, Souza et al., 2005). Даже в тех случаях, когда речь идёт не о пользовательских руководствах, а о поясняющих комментариях внутри кода, у разработчиков нет чётко выработанной практики регулярного комментирования и обновления имеющихся комментариев вместе с программой (Linares-Vбsquez et al., 2015). Между тем, на практике при освоении новой программы или проверки функциональности сами программисты опираются в основном на исходный код (даже не имеющий комментариев) и на устную информацию, полученную от коллег (Roehm et al., 2012).

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

Во-вторых, программистам зачастую просто некогда заниматься документированием создаваемых функций, особенно в условиях работы по гибким методологиям, таким как agile или scrum. За разработкой программ, их отладкой и проверкой на написание документов до момента выпуска не остаётся времени, а после выпуска все усилия идут на поддержку текущей версии и разработку новой. К тому же разработка для программистов - куда более мотивирующая и воодушевляющая задача, чем описание уже созданной функции для будущих пользователей (Sukale & Pfaff, 2014). А тот факт, что разработчики общаются между собой и всегда могут уточнить необходимую информацию у коллег, ещё больше снижает приоритет документации в списке задач, и в итоге её так и не успевают написать или обновить.

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

Несмотря на все эти факторы, иногда разработчики всё же занимаются документированием создаваемых и изучаемых программ и функций. В основном это происходит в тех случаях, когда составление документации входит в список требований к новой функциональности и без них нельзя отметить соответствующую задачу в проекте как выполненную. И хотя в основном программисты неохотно занимаются документацией и обращаются к ней далеко не в первую очередь, они всё же считают любую документацию к продукту очень важной и полезной, даже если документация давно не обновлялась или не совсем соответствует действительности, но сохраняет актуальность на высоком уровне абстракции (Lethbridge & Singer & Forward, 2003).

Конечные пользователи также признают важность документации для понимания и освоения нового продукта, причём хорошая документация пользуется вниманием и у начинающих пользователей, и у уже опытных. Однако в целом они читают руководства достаточно редко, только когда появляются проблемы и другие способы (например, спросить у коллеги или попробовать решить самостоятельно) себя исчерпывают. Причём пользователи предпочитают использовать онлайн-документацию, а не её печатный вариант, что вполне объяснимо в современном мире. Novick и Ward в одном из своих исследований пользователей отмечают, что печатные руководства настолько уступают в популярности веб-версиям и форумам, что иногда пользователи не пользуются ими годами, хотя регулярно обращаются за помощью к Интернет-ресурсам (Novick & Ward, 2006).

При этом в случае отношения пользователей к документации наблюдается куда большее разногласие, чем у разработчиков. Связано это с тем, что если программисты обладают приблизительно одинаковыми базовыми знаниями, то опыт пользователей может варьироваться от нулевого до продвинутого, но за помощью они обращаются к одной и той же документации. Этим объясняются две полярные точки зрения: документация либо «слишком простая», либо «слишком сложная» (Novick & Ward, 2006). Так как пользователям с разным опытом необходим разный уровень абстракции и подробности в объяснениях, очень редкая документация может угодить всем и сразу. Кроме того, даже при очевидном предпочтении онлайн-документации печатным руководствам, пользователи отмечают две главные проблемы, сопутствующие многим порталам с веб-документацией: навигация и поисковая система.

Проблемы с навигацией заключаются как в том, что сама ссылка на сайт с документацией отсутствует или её тяжело найти, так и в отсутствии содержания в самом документе (в случае с объёмными руководствами это особенно актуально). Кроме того, ссылки на сопутствующие разделы или разделы с похожими темами могут заводить пользователя в замкнутый круг, но так и не приводить к решению проблемы. В таких случаях пользователи пытаются найти ответ с помощью внутреннего поискового индекса. Далеко не у всех сервисов документации он есть, но даже при его наличии зачастую сложные поисковые запросы с соответствующим синтаксисом не поддерживаются, и для нахождения именно нужной информации надо суметь подобрать правильный запрос, что удаётся сделать лишь методом проб и ошибок. При всей сложности с поиском пользователи отмечают, что найти правильный раздел с помощью оглавления было бы проще, но, когда отсутствуют и навигация, и поисковый индекс, быстрее задать вопрос на форуме или поискать в Интернете (Novick & Ward, 2006).

Несмотря на все проблемы онлайн-документации и неприятие пользователями печатных версий руководств к продуктам, официальные документы от компании-производителя остаются одним из самых предпочитаемых и регулярно используемых источников информации о продукте (Earle & Rosso & Alexander, 2015), несмотря на появление интерактивных туториалов, обучающих видео, тематических форумов и блогов. Поэтому задача поддержания документации полной и актуальной остаётся важной для компаний самого разного уровня, и если небольшие проекты и компании, создающие специализированные инструменты для разработчиков, могут получать документацию из кода и использовать помощь сообщества для коллаборативного создания документации, то большим корпорациям, выпускающим документы для массового пользователя, созданные отдельной командой технических писателей, приходится сложнее.



1.3 Автоматизация документации

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

Документация из кода

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

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

Одним из самых ярких примеров близкой к коду документации (помимо уже разобранной выше документации к языкам программирования, которая часто пишется усилиями сообществ людей) является документация REST API. REST (Representational State Transfer), впервые представленный в 2000 году, активно используется для связи со множеством сервисов. Чтобы другие сервисы могли использовать API, необходима понятная документация, описывающая все возможные запросы и приходящие на них ответы. Как отметили Sohan, Anslow, и Maurer, документация API должна не только быть полной и правильной, но и включать в себя примеры кода с объяснением и возможностью тестирования запросов в браузере, а также быть правильно организованной и единообразной (Sohan, Anslow, Maurer, 2015). Между тем, в большинстве случаев создание документации API автоматизировано только частично.

У полностью ручного написания документации API, помимо очевидной трудоёмкости и неустойчивости к человеческим ошибкам, есть и другие недостатки. Так, примеры кода и списки запросов с коротким их описанием куда более наглядны, чем описанные человеком пошаговые процедуры работы (из чего в основном состоят руководства пользователей), и их проще автоматизировать, а значит, легко сохранять актуальными. К тому же подобные документы легче сделать интерактивными и позволить пользователю тестировать запросы прямо в браузере. Для создания подобных спецификаций используются такие инструменты, как Swagger, API Blueprint, RAML, основанные на различных языках разметки. Однако они не привязаны к протоколу HTTP и могут служить только как промежуточный инструмент. Для полной автоматизации процесса разработчикам приходится создавать новые инструменты самостоятельно (Sohan, Anslow, Maurer, 2017).

С похожими целями используются программы-генераторы, собирающие документацию из особым образом откомментированного исходного кода, такие как Javadocs, Doxygen, Epydoc, Sphynx и другие. Однако в данном случае, то, что при создании документов по API было достоинством - краткость и техничность описаний, которые затрагивают только код определённой функции, - может стать недостатком, поскольку конечным пользователям нужна не только информация о том, что делает та или иная функция, но и информация о её месте в сервисе и связи с другими функциями.

Если некоторые генераторы документов могут по совокупности функций выстроить структуру сервиса, то необходимые объяснения принципов их работы приходится дописывать вручную, либо создавать для этого отдельные фреймворки, которые дополняют работу генераторов с помощью дополнительного анализа исходного текста и, иногда, методов машинного обучения (McBurney & McMillan, 2014). Особенно подобные решения помогают в создании отдельного типа технической документации - release notes, которые содержат краткое описание изменений и новых функций выпускаемой версии продукта и чаще всего пишутся именно разработчиками, в отличие от пользовательских руководств, за которые отвечают технические писатели (Moreno et al., 2014).

Автоматизация разноформатной документации

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

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

Такой подход изначально был заимствован из сферы разработки программного обеспечения и постепенно распространился на другие области, включая создание технической документации. Сейчас он в основном применяется в тех областях, где документация является основным результатом работы (в основном это законодательная сфера) либо в тех, где документы составляются индивидуально, иногда самими пользователями под свои нужды (Gуmez et al., 2012, Lehtonen et al., 2002). Один из основных представителей этого направления работ - подход Document Product Lines (Penadйs et al., 2010).

В этом подходе документ делится на содержание и представление (формат, расположение на странице и т.д.), а содержание, в свою очередь - на шаблон и наполняющие его данные. Если данные могут меняться и их создание - работа технических писателей, то шаблон чаще всего остаётся неизменным, и при сборке документа он наполняется нужными данными по выбору собирающего. Если какой-то блок данных повторяется в нескольких местах, его можно написать один раз и вставлять в каждый шаблон, где этот блок должен быть. Такой принцип сборки документов позволяет не только существенно экономить усилия технических писателей, но и создавать персонализированные документы, чем пользуются авторы множества модифицирующих DPL-подход решений, позволяющих пользователям самим собирать документы с нужной информацией (Gуmez et al., 2012, Lehtonen et al., 2002). В таком случае техническим писателям остаётся только поддерживать актуальную информацию в отдельных блоках с данными, вся работа по сборке документов с иногда повторяющимся текстом переходит к заинтересованным в этом пользователям.

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

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

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

Первое решение помогло объединить работу нескольких отдельных сервисов и трансформировать ручное создание технических диаграмм и описаний в удобный веб-сервис (Buchgeher et al., 2018). Оно разработано для компании по производству перерабатывающих машин и направлено на решение следующих проблем, общих для многих подобных ситуаций: обилие устаревшей информации в документах и полное отсутствие нужной информации, отсутствие проверки качества документов и разбросанность данных по одной теме в разных документах. Решение концентрируется на автоматической генерации диаграмм, описывающих работу системы.

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

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

Некоторые решения по автоматической сборке документов адаптируют и видоизменяют подход Document Product Lines, добавляя в него элементы других парадигм или упрощая сам подход DPL. Например, фреймворк DPLfw, который, как и изначальный DPL, был создан для сборки изменяющихся документов в государственной сфере (Gуmez et al., 2012). Он поддерживает основное в DPL разделение документа на изменяющуюся и неизменную части и также разделение ролей по редактированию документов: отдельный специалист редактирует шаблон, по которому собирается тот или иной документ и все свойства документов, а другой - наполняет шаблон нужным содержанием. Благодаря подключенному хранилищу уже созданные документы или их части можно использовать повторно при сборке новой документации.

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

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

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

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

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

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



ГЛАВА 2. ОПРЕДЕЛЕНИЕ ДИЗАЙН-ФРЕЙМВОРКА И МЕТОДОВ ИССЛЕДОВАНИЯ

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

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

2.1 Contextual design

Любой создаваемый продукт, будь то отдельное приложение, сервис или функциональность, существует не обособленно, а в рамках большой системы - внутреннего контекста работы пользователя. В этом контексте он сосуществует с другими инструментами, вместе с которыми используется, и с действиями, выполняемыми непосредственно пользователем (Beyer, Holtzblatt, 2016, p. 8). Поэтому разработка этого продукта должна учитывать большой контекст, чтобы в будущем вписаться в него и улучшить жизнь пользователя на всех этапах взаимодействия с системой. Дизайн-фреймворк, направленный не только на изучение конечных пользователей, но и на исследование контекста работы и жизни, который будет затрагивать продукт, получил название Contextual Design (CD) или, если переводить дословно, Контекстный дизайн. Он был впервые представлен в 1988 году и переработан спустя более чем 20 лет, в 2013 году Hugh Beyer и Karen Holtzblatt (Beyer, Holtzblatt, 2016).

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

Процесс проектирования в рамках CD подхода состоит из трёх основных шагов:

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

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

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

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

2.2 Контекстное интервью в процессе генерации документов

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

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

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

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

2.3 Интервью с техническими писателями

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

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

Определить функции, которые необходимо сохранить в новом сервисе;

Определить новые функции и потенциальные преимущества, которые упростили бы работу со сборкой документов.

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

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

...