Прилипухова Алина

Ведущий аналитик

Всем привет! На связи снова Алина — аналитик продукта Тил Эйчар. 

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

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

Введение

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

  1. Большой поток однотипных вопросов от пользователей;

  2. Передача функций технической поддержки в стороннее подразделение;

  3. Сокращение временных затрат на поддержку пользователей внутри команды;

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

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

Главный вопрос, который возникает на начальном этапе: «Кто займётся написанием инструкции в команде?»

Тоби Магуайр, Эндрю Гарфилд и Том Холланд повторили мем с двойниками  Человека-паука, показывающими друг на друга! | Пикабу

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

Какие возникли проблемы и почему они возникли?

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

После первого подхода на этапе ревью выявились следующие проблемы:

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

  2. Инструкция была плохо структурирована:

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

    2. Отсутствовали перекрёстные ссылки на главы или хотя бы наименования разделов, где были описаны взаимозависимые сценарии;

  3. Частично были приложены скриншоты не с демо-кабинета, а с тестового стенда;

  4. Не хватало описания альтернативных сценариев и/или сложной бизнес-логики.

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

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

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

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

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

Работа со скриншотами поделилась на 2 части:

  1. Те скриншоты, которые можно было сделать с демо-кабинета, нужно было заменить;

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

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

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

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

Как можно было предотвратить эти проблемы?

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

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

  1. Как инструкция делится по ролевой модели: у вас будет общая инструкция для всех ролей или отдельные для каждой роли? Есть проекты, где помимо ролей используются ещё и пермиссии (от англ. permissions — разрешения), и одна и та же пермиссия может быть присвоена разным ролям. Если нужно скрывать от пользователей, которые не имеют соответствующей роли и/или пермиссии недоступную им функциональность, то стоит об этом сказать сразу.

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

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

  4. Какая структура будет у инструкции.
    Вы разделите её по бизнес-смыслу, пользовательским сценариям, разделам в вашем приложении и т.д. 

  5. Что с внешним видом.
    Важно ли вам, чтобы скриншоты не содержали сущности с наименованием «Тест1234_проверка»? Чтобы они были в едином стиле? Для функциональности, которая сейчас дорабатывается, стоит подготовить скриншоты до очередного обновления, чтобы они сходились с инструкцией.

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

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

Заключение

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

А какой у вас был опыт, связанный с инструкциями для пользователей?

Комментарии (10)


  1. little-brother
    10.09.2024 09:02
    +1

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

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

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


    1. UseTech Автор
      10.09.2024 09:02

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


    1. Elpi
      10.09.2024 09:02

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

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


      1. UseTech Автор
        10.09.2024 09:02

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


        1. Elpi
          10.09.2024 09:02

          Вопрос был к Младшему Брату. Языки ладно. Но замечание об устарелости статичных скринов любопытное. И непонятное. Если у клиента стоит версия №5 (условно), то и скрин ему нужен этой версии. А остальные вообще не в тему. Учитывая, что инструкции обновляются по версиям продукта вообще не вижу тут проблемы. Поэтому и спросил.
          Вам за ответ спасибо.


      1. little-brother
        10.09.2024 09:02

        Типа сделать ПО, где модульно все подтягивается - в зависимости от языка и также модульно редактируется, а "скриншоты" генерятся автоматически из актуальной версии ПО (гуй + язык). Под скриншотами имхо лучше понимать "миниролики" куда кликаться, чтобы получить необходимый результат, а не как сейчас у большинства: адский мануал + ролики на ютубе.

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

        Для конечного клиента, конечно нужно показывать хелп нужной версии. Но у вас же не один клиент с одной версией ПО?


  1. NomLi
    10.09.2024 09:02
    +1

    Например. есть инструмент для видео ffmpeg Многие пользуются, я в том числе. Но его man да и readme в гитхабе читать раньше было невозможно. Огромный поток бессмысленной информации для пользователя, которому надо сделать типовое простейшие действие. Например, быстренько что-то во что-то сконвертировать. Вместо это авторы долго и упорно рассказывают о своих макросах, чудесных опциях ипр. В итоге пользователь идет в гугл и где-нибудь на stkxchg находит примитивную инструкцию -i имя файла входного формат разрешение имя выходного. По своему опыту - 99% пользователей этой информации более чем достаточно. Чего ради авторы неплохого инструмента так засирают ридми совершенно не понятно. ЧСВ?! Нужны автоматизированные системы написания пользовательской документации, где будут учитываться наиболее частые случаи использования продукта. Времени мало, тратить его на чтение портянок уже никому не хочется.