Всем привет! Меня зовут Ксения Непомнящая, я — технический писатель в команде Zyfra Mass & Energy Balance (Z-MEB) компании «Цифровая индустриальная платформа». Z-MEB — это продукт для предприятий добычи и переработки нефти, газа и руды, участвующий в программе импортозамещения. Сегодня предлагаю вам взглянуть на пользовательскую документацию как на путеводитель по продукту и рассмотреть ее роль в увеличении ценности продукта.
Понятный интерфейс как город с понятной планировкой и развитой инфраструктурой
Представим себе город с понятной планировкой и развитой инфраструктурой и рассмотрим два варианта взаимодействия с ним:
Человек недавно переехал в город.
Человек в городе живет давно.
В первом случае человек может рассчитывать на свое понимание возможного расположения нужных ему учреждений в городе. Например, он остановился в центре города и решил не смотреть ни на карту, ни в путеводитель. Ведь в центре, скорее всего, есть аптеки, кафе и что-то интересное, на что можно посмотреть. Однако он потратит больше времени, чтобы их найти, и найдет не самые лучшие варианты, чем если бы он сначала подготовился.
Во втором случае человек чаще всего ходил или ездил одними и теми же маршрутами и не знает о новых интересных местах, выгодных предложениях новых магазинов и что в пяти минутах ходьбы от его дома появилась остановка с удобным маршрутом до его работы. Он бы знал это, если бы следил за изменениями в городе и пробовал использовать новые возможности.
В случае с продуктом новый пользователь также может сориентироваться по его использованию, если у продукта будет понятный интерфейс. Однако он потратит больше времени на ознакомление, может совершить ошибки при выполнении первых операций в программе, а также не сможет использовать возможности, которые лежат не на поверхности. Опытный пользователь продукта допустит меньше ошибок и со временем методом проб и ошибок обнаружит даже скрытые возможности продукта. Если такой пользователь не будет знакомиться с документацией по новым версиям программы, он упустит возможности новых обновлений или найдет их с большим опозданием.
Интуитивно понятный интерфейс — важная составляющая взаимодействия программы с человеком. Развитая инфраструктура и удобная планировка — важная составляющая взаимодействия города с человеком. Для обычной жизни обычного человека этого может быть достаточно. Если горожанин стремится успевать много и использовать окружающее его пространство эффективно — ему нужна дополнительная информация о том, что есть в этом городе, где это находится и как это работает. С программным обеспечением так же: можно догадаться об использовании тех или иных элементов интерфейса и с опытом перестать совершать ошибки, но если цель — использовать программу эффективно, без документации не обойтись.
Документация прокладывает маршруты и открывает двери к скрытым возможностям
Чтобы использовать развитую инфраструктуру города на 100%, горожанину необходимы карта, путеводитель и новости об изменениях в городе. Чтобы использовать программу на 100%, пользователю необходима документация: описание продукта и интерфейса, руководства пользователя и администратора, Release Notes с новостями о новых возможностях. В обоих случаях нужную информацию могут предоставить и специальные люди: в городе экскурсоводы и отдельные местные жители, которые в курсе последних новостей, по программе — специалисты по обучению. Это более дорогостоящий метод получения информации, и он ограничен во времени. В отличие от путеводителя, экскурсовод не будет с вами всегда.
Документация позволяет эффективно выполнять операции, для которых предназначена программа. Она прокладывает лучший маршрут от одного элемента интерфейса к другому через последовательность действий. Документация выступает планировщиком маршрутов, который показывает кратчайший путь к цели.
Документация подсвечивает скрытые возможности продукта. В понятном интерфейсе сразу видны базовые возможности. Однако в сложных программах часть функциональности всегда недоступна для использования без прочтения документации, прохождения обучающих курсов или советов от опытного пользователя. Как было отмечено выше, советы и курсы — это более дорогостоящее обучение, чем обучение по документации.
Обучение по документации возможно только в том случае, если документация выполнена качественно. В такой документации должна быть представлена исчерпывающая информация, и она должна быть понятна пользователю.
Как мы прокладываем маршруты по взаимодействию с нашими продуктами
Давайте рассмотрим, какие особенности качественной пользовательской документации и процесса документирования позволяют прокладывать маршруты и подсвечивать скрытые возможности продукта. Опишу особенности документирования, которые мы привносим в нашу деятельность на пути к созданию качественной документации.
1. Следование рекомендациям в ГОСТах. Не все, но многие рекомендации в ГОСТах позволяют сделать документацию важным дополнением к понятному интерфейсу. Применение ГОСТов в технической документации сейчас необязательно, но многие указанные в них требования обоснованы. Например, в наших руководствах пользователя представлены разделы о назначении программного обеспечения и основных операциях, которые в нем можно выполнить.
Раздел о назначении программного обеспечения составляет общее представление о сферах применения и целях использования продукта. Он очерчивает радиус взаимодействия человека с программой. Если продолжать аналогию с городом и путеводителем, в данном разделе уточняется, к какому району или какой сфере жизни города относятся маршруты путеводителя.
В разделе об основных операциях перечисляются основные операции, которые можно выполнить при помощи описываемого программного обеспечения. Этот раздел позволит разглядеть за интерфейсом не несвязанные между собой компоненты, а маршруты из набора действий.
2. Связь между разными разделами и разной функциональностью. Информация в разных разделах не должна противоречить друг другу: назначение программного обеспечения, описание интерфейса и основных операций — все должно быть взаимосвязано. Если есть важная функциональность, которую можно использовать в интерфейсе, мы стремимся описать ее и в разделе о назначении, и в разделе об основных операциях. Также мы стараемся создавать внутреннюю связь между разделами при помощи перекрестных ссылок. Это не всегда получается, но мы понимаем, что пользователю с ними удобнее. Поэтому, где это возможно, стараемся их указывать.
3. Связь между документами. Если по одной из затронутых тем подробная информация содержится в другом документе, мы уточняем это с указанием наименования документа. В документации по Z-MEB есть отсылки между руководством пользователя, администратора и описанием продукта, а также на руководства ZIIoT. Z-MEB работает на основе ZIIoT — другого продукта «Цифровой индустриальной платформы». На ZIIoT поступают данные с датчиков и контрольно-измерительных приборов, а оттуда попадают в сервисы Z-MEB для расчета баланса и других операций. Отсылки на документацию ZIIoT необходимы как для правильных настроек, так и для понимания работы продукта.
4. Актуальность информации. Неточность в документации может сказаться на понимании функциональности. Мы выпускаем документацию к релизам и публикуем ее одновременно с ними. Перед выходом релиза документация проверяется аналитиками на наличие в ней информации по новой функциональности. В актуализации информации хорошо помогает участие технического писателя в приемке историй от аналитиков к тестированию. Аналитик показывает реализованную функциональность, а QA и технический писатель задают свои вопросы. QA смотрят на продукт под своим углом, и их вопросы часто открывают новые аспекты обсуждаемой функциональности.
5. Отсутствие неосвещенных тем. Неосвещенные темы затрудняют понимание функциональности: это может быть необозначенная взаимосвязь между компонентами продукта или неописанная деталь интерфейса. Мы следуем двум правилам борьбы с неосвещенными темами. Во-первых, тщательно проверяем новую функциональность релиза на предмет того, что необходимо описать. Во-вторых, как только появляется понимание, что какая-то тема не была описана в документации, стараемся описать ее к следующему релизу.
6. Точность и ясность формулировок. От точности и ясности формулировок зависит понимание непростых тем. Функциональность должна быть описана такой, какой она является в реальности в выпускаемом релизе: без преувеличений и преуменьшений. Это не только про популярное сейчас: сокращайте и приводите все к простым предложениям. Иногда для ясности необходимо использовать новый термин вместо старого: найти его, уточнить у аналитиков, насколько он подходит для описания продукта, свериться с редакционной политикой, при необходимости внести его в словарь терминов.
В создании нового термина также немаловажно найти баланс между точностью и ясностью. Точность в техническом описании иногда мешает ясности. Некоторые детали лучше опускать: для руководства администратора наличие большого количества технических деталей считается нормой, в руководстве пользователя их не должно быть много.
7. Структурирование информации с акцентом на важном. Понятно, что в начале любого перечисления стоит указывать важное, далее — дополнительное. Например, перечисление компонентов интерфейса стоит начинать с основного компонента, а описание компонента интерфейса — с описания его назначения. Но есть сложность со внесением изменений к релизу. С появлением новой функциональности важное иногда становится второстепенным, а второстепенное – важным. Мы стараемся замечать это во время обновления документации и менять акценты.
В целом, документ должен вызывать ощущение завершенности и отвечать на вопрос о том, как организовать работу в программе для достижения поставленной цели. Если ответа на вопрос нет, нужно обращаться к команде с дополнительными вопросами и дописывать документацию до тех пор, пока в ней не будет ответа.
Документация уменьшает затраты на интеграцию нового продукта
Выше мы рассмотрели сравнение пользовательской документации с путеводителем, увидели на примерах, как документация прокладывает маршруты по продукту и подсвечивает скрытые возможности. Далее мы разобрали, какими качествами должна обладать документация и процесс документирования, чтобы обучение пользователей проходило гладко, а их работа с продуктом была эффективной. Полученная в результате документация позволяет уменьшить затраты на интеграцию нового продукта в компании и тем самым увеличивает ценность самого продукта: обучает пользователей методам работы с программой и позволяет выполнять поставленные задачи с первых дней взаимодействия.