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

У многих, кто сталкивался с разработкой инструкций, возникали вопросы:

• Кто должен разрабатывать инструкции?

• Как лучше организовать в них структуру информации?

• Как сделать инструкции быстро?

• Применять ли стандарты?

• Что делать с устареванием инструкций?

• Насколько детально нужно описывать продукт?

• Почему инструкции не читают? Или почему они не работают?

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

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

Не все понимают, что ИТ-система – это не просто программа, которую купили. ИТ-система всегда состоит из трех основных компонентов.

• Сам по себе программный продукт.

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

• И третья немаловажная часть – это люди, персонал, который будет работать с этой системой.

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

Посмотрим, какие вопросы могут возникать по поводу этих компонентов в системе.

Программный продукт:

• Может оказаться сложным.

• Может иметь множество настроек – быть сложно настраиваемым, как Комплексная автоматизация или ERP.

• Может постоянно меняться, дорабатываться.

• Может иметь множество вариантов использования – когда один и тот же документ выполняет множество разных операций.

Со стороны оборудования и инфраструктуры у нас могут быть задачи:

• интеграции с оборудованием.

• вопросы отказоустойчивости и производительности,

• работы серверов и так далее.

И со стороны персонала тоже могут быть вопросы:

• Персонал может оказаться не готов к использованию программного продукта – начиная с того, что он плохо работает на компьютере.

• Пользователи могут часто задавать одни и те же вопросы.

• Они могут меняться – нужно, чтобы сотрудники могли быстро погрузиться в нашу систему.

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

• И, конечно же, пользователи должны быть в принципе подготовлены к работе с информационной системой. Например, если вы внедряете систему автоматизации бухгалтерии, пользователь должен знать, что такое Дебет и Кредит. Если он не понимает, что такое бухучет, с ним работать сложно. Это подразумевает, что документация к продукту может предъявлять и требования к квалификации персонала – я позже этот момент подробнее затрону.

Отсюда выводы:

• Поскольку система состоит из нескольких компонент, возникает понятие видов документов. Для разных составляющих системы нужны разные виды документов. Оттуда и рождается «Руководство администратора», «Руководство системного программиста». Но мы сейчас будем говорить только об одном виде документов – о «Руководстве пользователя».

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

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

Что касается первого компонента – программного продукта, нужно понимать, что это не программный код.

Я часто сталкивался с тем, что когда заказчику передают систему, он спрашивает: «А где инструкция?», и в этот момент ему начинают продавать разработку документации.

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

• Программный код и документация нужны определенным пользователям.

• А сам продукт – поставляется заказчику.

Это очень важно.

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

Для чего нужны инструкции – тому, кто использует, и тому, кто создает? И нужны ли они вообще?

Пользователям инструкции нужны, чтобы:

• понять, как выполнять операции в системе;

• научиться самостоятельно решать проблемы;

• ознакомиться с продуктом в целом;

• знать, как что-нибудь сломать – но не для того, чтобы сломать, а для того, чтобы, наоборот, этого не делать.

А нам, айтишникам, нужно, чтобы инструкции были у пользователей, чтобы:

• упростить использование продукта;

• повысить лояльность к продукту, потому что продукт с хорошей документацией выглядит более качественно;

• обучить пользователя – такая задача тоже может решаться;

• нельзя отрицать и формальное исполнение запроса на разработку документации в таком-то виде;

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

Когда мы глядим на все это вместе, у нас вырисовывается определенная структура.

Что касается структуры пользовательской документации, для этого есть разные ГОСТы – старые ГОСТы, новые ГОСТы, российские ГОСТы, иностранные ГОСТы.

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

На слайде я синтезировал структуру пользовательской документации в упрощенном виде:

• Обязательно должно быть введение – о чем эта система.

• Оглавление – тоже понятно.

• Глоссарий.

• Основное содержание.

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

• Описание аварийных ситуаций.

• Желательно иметь предметный указатель.

• И список источников дополнительной информации.

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

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

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

Мы можем столкнуться с ситуацией, что пользователи инструкцию не читают.

Более того, они ее не только не читают, они могут даже саботировать чтение инструкции.

Вы им говорите: «Это написано в инструкции». А они говорят: «Она у вас сложная, большая, непонятная. И нам некогда ее читать. Лучше сделайте простую систему» и так далее.

Почему такое может происходить?

Если посмотреть информацию по написанию инструкций в интернете, там, в основном, упоминается два стиля: классический – описательный и сценарный.

• Описательный стиль вы наиболее часто видели в документации, сопровождающей программные продукты 1С – это те книги, которые идут вместе с коробкой. Там идет описание по объектам: сначала описываются справочники, потом документы, и так далее – все последовательно описывается.

• Сценарный стиль – это когда использование продукта описывают по процессам и по задачам.

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

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

Описательный стиль:

• Он компактный – там просто все последовательно изложено.

• Такой подход легко включать в справку продукта – там есть описание к каждому объекту.

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

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

И есть сценарный подход к написанию инструкций. Если вы сталкивались, часто к сложной бытовой технике пишут «Руководство по быстрому старту». Там в комплект входит талмуд – полная инструкция, и есть пара страничек с руководством по быстрому старту, где написано, как включить, как выключить, как что-то сделать. Простые операции по шагам – первое, второе, третье. Если вам нужно подробнее, то смотрите в полную инструкцию.

Преимущества сценарного стиля:

• Быстрый старт для пользователя.

• Легко адаптировать под бизнес-процессы, потому что стиль описания такой инструкции соответствует тем бизнес-процессам, которые система автоматизирует.

Вроде бы все хорошо, но есть минусы.

• Сценарный подход объемный, у него много повторений, потому что, если у вас там будет описание какого-то процесса – например, работа со справочником «Номенклатура» – тогда вам и при описании другого процесса придется описывать то же самое. Получается много повторений-копипастов.

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

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

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

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

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

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

Честно говоря, я тогда сделал его первый раз в жизни, мне было непонятно, как он зайдет. Но они были просто в восторге и рады, что стало так классно, и все понятно.

После этого еще много раз применял, и это всегда нравилось.

Гибридный подход берет себе лучшее из описательного и сценарного:

• Быстрый старт для пользователя.

• Понятность процессов.

• Простота актуализации.

• Нравится пользователям.

Но есть и минусы:

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

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

Инструкция по ГОСТ? Или в произвольном виде?

Использовать стандарты или не использовать стандарты? Тут вопрос очень специфический.

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

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

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

Не надо циклиться на стандартах. Есть такие люди, которые говорят: «Не надо ничего выдумывать, все давно придумано, в стандарте описано. Возьмите ГОСТ, там хорошая структура документации, просто делайте». Но тогда у вас получается классический описательный стиль, который потом у пользователей не работает.

Еще такой вопрос – кто должен разрабатывать инструкции? Тоже многие спорят.

• Аналитики.

• Технические писатели.

• Руководитель проекта – конечно, он редко пишет инструкции, но если это микропроект, где работает пара человек, то вполне вероятно, что и руководитель проекта может писать.

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

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

И вообще спорить на эту тему не надо, это глупый спор, совершенно никому не нужный.

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

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

Разделение сбора и передачи знаний – технология для быстрого создания инструкций

Приближаемся к самому главному – как создать инструкцию быстро?

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

• Логично разработать шаблоны со структурой нашей документации.

• Желательно согласовать этот состав документации с заказчиком, чтобы не возникало потом вопросов, чтобы не переделывать.

• Но два самых главных момента – это сбор информации и оформление. Эти два процесса можно между собой разделить.

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

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

Берется такой человек-эксперт, и к нему подсаживается совершенно другой человек, который систему не знает, но научен грамотно документировать. Понимает, что такое документация, знает, как сделать скриншот с экрана, и как все описать – он это умеет.

Они включают режим видеозаписи, открывают систему, и эксперт начинает по системе все методично рассказывать, показывать – видео и аудио записывается.

Человек, который наблюдает за этим (он ближе к техническому писателю) задает вопросы, если эксперт что-то пропускает.

В результате за 2-3 дня можно таким образом рассказать о довольно большой системе. А за неделю или две можно рассказать просто о гигантской системе.

Остается очень качественный материал – видео и аудиозапись о том, как эта система работает.

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

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

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

• А если эта инструкция большая, бюджет на нее получается космический. Бюджет разработки документации от того и получается космическим, что эту задачу поручают людям, которые не должны делать документацию.

Разделение сбора и передачи знаний – очень важно.

Абстракция или детали?

По поводу вопроса «Насколько подробно описывать продукт?» – здесь нет четких стандартов и установок.

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

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

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

Актуализация инструкций

Отсутствие актуализации – это одна из причин, почему инструкция умирает, и ею перестают пользоваться.

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

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

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

Что касается актуализации, у нас есть три потока информации, которые можно использовать для актуализации.

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

  • Некоторые актуализируют инструкции при каждом изменении в системе.

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

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

• Второй поток информации у нас понятный – это «Часто задаваемые вопросы». Если вам постоянно задают одни и те же вопросы, то логично, что вы в первый раз неудачно сделали инструкцию, лучше ее актуализировать и дополнить так, чтобы у человека эти вопросы больше не возникали.

• Еще один интересный момент – я его назвал «Контрольный пользователь». Это человек, который активно пользуется системой. Допустим, у вас в системе работает 10 менеджеров, кого-то одного надо попытаться назначить контрольным пользователем, который ничего не делает без инструкции. У него жизнь такая – он все делает четко по инструкции и сразу же оперативно в момент отклонения системы от документации дает обратную связь техподдержке, что какой-то процесс по инструкции сделать нельзя. Когда у человека есть явно вмененная обязанность следить за актуальностью инструкций, это не дает системе и документации отойти друг от друга.

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

Выводы

Перейду к итогам – что я вам хочу посоветовать:

• Разработайте хорошие шаблоны инструкций.

• Выберите свой стиль описания. Советую попробовать гибридный формат.

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

• И продумайте процесс актуализации.

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

Вопросы и ответы

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

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

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

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

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

А в остальном – все то же самое.

Насколько уместны видеоинструкции? Есть ли смысл применять их? Был ли у вас опыт их использования?

Видеоинструкции, они, конечно, уместны, их применяют, но тут самое главное, чтобы они были очень короткими. Если у вас видеоинструкция 15-20 минут – скорее всего, это будет плохо работать.

Короткие видеоинструкции, типа 1-2 минуты – скорее, хорошая практика, чем плохая. Это будет работать точно.

Главное – правильно сделать структуру таких инструкций, чтобы человек быстро мог их найти, и ему было все быстро и понятно. Это 100% работает, это использовали.

Какой инструмент вы применяете для организации репозитория инструкций? У нас сейчас инструкция – это просто каталог вордовских файлов, а это огромные проблемы с версионированием, с отслеживанием, кто что поменял. Какие есть более современные подходы для репозитория?

Не в инструменте дело. Главное – в подходе, в том, как вы этот инструмент используете. Даже если у вас инструкции в Word, но процесс их актуализации налажен, это будет лучше, чем использовать инструмент, не используя процесс актуализации.

Если бы вам нужно было дать один совет человеку, который только-только начинает внедрять систему пользовательских инструкций у себя в организации, что бы вы посоветовали?

Я бы вам посоветовал, наверное, идти разговаривать с группой пользователей – какие инструкции они читают, а какие не читают.

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

А так, конечно, нужно изучить опыт коллег, почитать книжки, посмотреть, что пишут в интернете, послушать, что говорят на конференции, а потом подумать.

*************

Статья написана по итогам доклада (видео), прочитанного на конференции Infostart Event 2022 Saint Petersburg.