Как мы в «Активе» пишем пользовательскую документацию. Почему это важно


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



    Нам мешает негативный опыт


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


    Да, через какое-то время вы всё-таки освоили систему и ловко жонглируете её процедурами, но чего это вам стоило? Вы потратили время, нервы и может даже не только свои. Что решило бы вашу проблему ещё на раннем этапе?


    Ответ один — хорошая пользовательская документация.


    Документация может всё


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


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


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


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


    В этой статье я расскажу вам о том, сколько в нашей компании стоит пользовательская документация, и из каких этапов у нас состоит процесс документирования. Let’s go!


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


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


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


    Весь процесс производства инструкции в нашей компании состоит из следующих этапов:


    1. Поставка задачи. Её создаёт и описывает менеджер проекта, руководитель проекта или руководитель отдела. На это нужно время, недостаточно просто написать “Опиши процедуру”. Здесь обязательно нужны детали. Например, здесь посчитаем 1 час рабочего времени менеджера проекта. На этапе постановки задачи менеджер проекта назначает консультанта и обозначает круг сотрудников компании, которые могут помочь и объяснят какие-то важные особенности системы. Получается, что цель этого этапа — сформулировать задачу и назначить консультанта



    2. Показ системы. Чаще всего здесь задействован системный аналитик, он демонстрирует систему техническому писателю и рассказывает, что и как работает. Прибавим 2 часа работы аналитика + 2 часа технического писателя. Здесь аналитик рассказывает, а технический писатель слушает и задаёт вопросы. Если система сложная, таких встреч может быть несколько. Цель этого этапа — объяснить техническому писателю, как работает система.



    3. Написание документа. Здесь главную роль играет технический писатель, но нельзя забывать про вопросы, которые у него могут возникать в процессе написания. Отвечать на них может аналитик, разработчик, менеджер проекта, тот, кто разбирается в продукте и умеет понятно объяснять. Таких вопросов может быть много и хорошо, если технический писатель оперативно получает на них ответы. Прибавим 20 часов работы технического писателя + 1 час работы аналитика + 1 час работы разработчика. Цель этого этапа — создать первую версию инструкции.



    4. Рецензирование. Чаще всего читает документ заказчик, в нашем случае — менеджер проекта. На это тоже нужно время, оно зависит от количества страниц в документе и качества описаний. Прибавим 2 часа работы менеджера проекта. На этом этапе он пишет комментарии к документу. Цель этого этапа — проверить документ.



    5. Внесение правок. Реализует технический писатель, на этом этапе он тоже может задавать уточняющие вопросы коллегам. Техническому писателю здесь очень важно правильно понять комментарии к инструкции. Прибавим 2 часа работы технического писателя + 1 час работы аналитика. Цель этого этапа — создать вторую версию документа.



    6. Тестирование. На этом этапе подключается сотрудник отдела тестирования. Он реализует все описания процедур и оценивает насколько корректно они описаны. Прибавим здесь 2 часа работы тестировщика. Цель этого этапа — проверить корректность описания процедур.



    7. Повторное внесение правок. Технический писатель получает от тестировщика комментарии и вносит изменения в инструкцию. Прибавим 1 час работы технического писателя. Цель этого этапа — создание третьей версии документа.



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



    9. Публикация документа. Мы публикуем документ на своём сайте на специальной странице. Прибавим 20 минут работы администратора сайта.



    Итого:


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


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


    100 тысяч рублей или долларов


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


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


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


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

    See you soon!

    «Актив»
    Компания

    Комментарии 5

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

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

      Держать своего тех писателя в штате слишком накладно, поэтому документация аутсорсится в одну жаркую страну, где стоимость человекочаса втрое ниже, чем в головном офисе. Техписатель продукт в глаза не видел — ему надо хоть что-то выдать, поэтому менеджер начинает бурную деятельность — на очередном статус-митинге он просит начальника отдела разработки выдать хоть что-то техписателям. Отдел разработки занят следующим проектом, поэтому это дело делегируется в отдел тестирования (ну или техподдержки, но зачастую и этот отдел находится в той же самой жаркой стране, где и документация). Тестировщик открывает продукт и начинает жамкать по клавише Print Screen, иногда видит там опцию типа «Выб. пров.», которую он не помнит, тогда он отправляет в ms team (ну или скайп) сообщение «это чё такое?». Через полчаса от разраба ему прилетает «это опция Выборочная проверка», ну там не влезло, я сократил.

      Тестировщик жамкает по клавише Print Screen ещё разок и пишет внизу «Выб. пров.» — Выборочная проверка", повторяет похожие действия для всех скриншотов и кладёт архив на сервер в папку проекта.

      Техписатель загоняет все скриншоты в систему документации (кстати, там не всё так плохо), дописывает «Опция „Выб.пров“ предназначена для включения режима Выборочной Проверки. Вы можете активировать режим Выборочной Проверки при помощи путём установки флажка в поле „Выб.пров. Для деактивации режима Выборочной Проверки снимите флажок с опции Выб.пров.“, в результате чего оно раздувается на 25 страниц текста и выплёвывает pdf. Менеджер даже не открывает этот файл — он просто ставит галочку в графе „документация“ и все довольны (кроме конечного пользователя). Всё идёт по плану.

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

      Вы, кстати, как локализацию документации на несколько языков делаете и в чём верстаете, если не секрет?
        0
        С первыми двумя абзацами трудно не согласиться, в 90% случаев так оно и есть. А дальше уже начинаются частности. Описанный пример относится к незрелым компаниям либо к тем, у кого продукт из b2c и он настолько прост, что никому и в голову не придёт вчитываться в документацию. Если компания посерьёзней и продукт посложнее (особенно если от него зависят деньги или безопасность), то и к документации требования другие, и процесс будет близок к тому, что описано в статье. А так да, «в мире реальном» есть куча примеров, когда нет ни аналитика, ни дизайнера, а разработчик выполняет ещё и функции тестировщика, девопса и техподдержки.
        0
        Андрей, здравствуйте! Спасибо за на мнение. Процесс документирования не всегда выглядит так, как я описала. Ваша история наверняка имеет место быть.
        Мы пишем только на русском языке сейчас. Верстаем документы в Конфлюесе, в следующих статьях я про это буду рассказывать.
          0
          На предыдущем месте работы у нас был примерно такой же процесс.
          Сейчас всё иначе, но зачастую техпис и тестировщик и администратор сайта, а еще сам уточняет постановку задачи.

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

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

            Самое читаемое