Клуб технических писателей

Особенности создания веб-документации для пользователей

Елена
5 марта 2015, 15:09

Мы начинаем серию публикаций с тезисами выступлений 2014 года. Сегодня речь пойдет о докладе «Особенности создания веб-документации для пользователей» с Гипербатона, прошедшего в рамках конференции Translation Forum Russia в Екатеринбурге.

Как писать, чтобы ответить на вопросы пользователя

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

Откуда мы берем вопросы?

  1. Смотрим, с какими проблемами обращаются в службу поддержки.
  2. Анализируем данные в Яндекс.Метрике ― узнаем, по каким поисковым запросам пользователи приходят в Помощь.
  3. Если сервис новый и пользователям еще не знаком, вопросы формулирует команда сервиса. Также сервис тестирует разработчик документации и описывает возможные пользовательские кейсы.

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

Как поддерживать качество документации

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

  • За каждым сервисом закрепляется один-два ответственных технических писателя. Такой подход позволяет авторам глубоко погрузиться в тему, исключить дублирование контента и оперативно поддерживать его актуальность.
  • В своей работе мы используем внутренние руководства по языку изложения и оформлению иллюстраций ― в них регламентируются основные моменты, разнобой в которых будет заметен или может помешать пользователю. Например, типовые обороты для описания интерфейса, использование технических терминов, оформление ссылок и т. п.
  • Практически для каждого инструмента у нас есть собственные шаблоны, которые мы применяем, чтобы не изобретать «велосипед» при выполнении типовых действий.
  • В работе над текстами руководствуемся несколькими принципами:
    1. Писать коротко и ясно.
    2. Разъяснять только неочевидное.
    3. Формулировать вопросы как пользователь.
    4. Вначале написать, что и зачем делать, потом объяснить ― как.
    5. Структурировать текст с помощью катов, табов, подразделов.

Как упростить поиск по документу

Вот несколько способов упростить поиск по документу:

  • Сделайте хорошую посадочную страницу, чтобы сформировать общее представление о вашем продукте.
  • Создайте отдельную страницу для каждой темы или группы связанных вопросов.
  • Используйте мини-оглавление для быстрого ориентирования на странице.
  • Разместите список полезных ссылок на статьи, к которым пользователи обращаются чаще всего или которые не включены в документ, но могут дополнить его.
  • Используйте двойные заголовки (тег <navtitle>) ― укажите короткий емкий заголовок в содержании, чтобы не перегружать его, а на странице напишите более подробный заголовок, который будет соответствовать запросу пользователя.
  • Укажите ключевые слова для каждой страницы (тег <keyword>) ― это те поисковые запросы, по которым пользователь приходит в вашу веб-справку.
  • По возможности поддерживайте адаптивную верстку для десктопных и мобильных платформ

Что нужно учитывать при подготовке текста к переводу

Сервисы Яндекса доступны в разных уголках планеты. И в каждой стране присутствия мы работаем так, как будто мы местные. Чтобы «говорить» с пользователем на одном языке, в документации:

  • Используем примеры и иллюстрации с местными географическими названиями.
    Русская версия на домене RU

    Русская версия на домене UA

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

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

  1. Пишем полную версию на русском языке. Она содержит все возможные варианты текста для разных доменов (стран) и языков, в том числе те, которые на русском публиковаться не будут.
  2. Делаем разметку в тексте, с помощью которой указываем, для каких языков и доменов (стран) написан каждый фрагмент.
  3. Отдаем на перевод отфильтрованную версию текста. В нее попадают только те фрагменты, которые нужны на конкретном языке. Фильтрация выполняется автоматически. После перевода получаем полную версию текста на русском языке и переведенные на разные языки версии для других стран.
  4. Перед публикацией снова выполняем фильтрацию и получаем несколько комплектов документации для разных доменов с нужным набором языков.

    Разметка текста


    Текст на домене RU
    Минимальная сумма заказа в Яндекс.Директе составляет 300 рублей.
    Текст на домене UA
    Минимальная сумма заказа в Яндекс.Директе составляет 81 грн.
    Мінімальна сума замовлення в Яндекс.Директі становить 81 грн.

В заключение

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

  • Мы пишем, чтобы ответить на вопросы пользователей.
  • При создании текста следуем принципу «мало букв — много смысла».
  • Структурируем тексты, чтобы упростить поиск по документу.
  • Стараемся говорить с пользователем на одном языке.

Посмотреть видео доклада и презентацию

4 комментария
Подписаться на комментарии к посту

Спасибо за статью! Вот интересно, сколько времени заняла разработка шаблонов описания типовых шагов и пр ("типовые обороты для описания интерфейса")? Кто и как этим занимался? Ведь обычно когда техпис понимает, что уже несколько раз он с нуля описывает схожий функционал, как-то не хватает времени/навыка/силы воли создать этот шаблон и применять его. Максимум на что хватает сил - это найти "кусок" в предыдущем документе и копи-пейстом вставить в новый. А обычно как-то проще писать заново...
Таким образом вопросы Елене:
- каким образом была организована работа по созданию шаблонов/типовых оборотов из, я так понимаю, уже описанных текстов?
-Сколько времени это заняло?
- В виде чего эти шаблоны/оборота хранятся?
- Посоветуете ли каким образом можно применять таки шаблоны в Ворде?

За основу типовых оборотов были взяты многолетние наработки наших писателей. Спорные моменты уточнялись с учетом мнения всех сотрудников службы. Обобщение и систематизация легла на плечи нашего редактора. Хранятся в виде руководства, которое все время дополняется. Поэтому оценить точное время, которое было затрачено на подготовку, сложно. При этом мы стараемся уже на этапе появления правил максимально их оптимизировать, чтобы потом не пришлось вносить правки во все наши документы.
Непосредственно к шаблонам относится, например, библиотека графических элементов для разработки иллюстраций и шаблоны для нашего редактора (Serna), в которые типовые фразы, чаще всего, не встроены.
Ворд мы не используем, поэтому могу дать только общие рекомендации: подготовить руководство по языку изложения (например, принять за правило писать от третьего лица, обращаться к аудитории на «вы» и т. д.), а также разработать шаблоны для редактора, чтобы документы имели схожую структуру.

Спасибо за публикацию!

Особенно понравилась фраза "Вначале написать, что и зачем делать, потом объяснить ― как" - очень актуально и объективно, чтобы у техписа не родились следующие предложения: "Нажимите на кнопку . Ждите окончания процесса. Теперь база данных компании с данными за 10 лет очищена!" :).

Не нашел в публикации ничего об информационных врезках, или как Вы "пугаете" читателя, например, Внимание!, Примечание!, Подсказка! и т. д.

Так держать, молодцы!

Врезки используем =) Тут действует правило: сначала в примечании сообщаем о важном, затем уже даем общую информацию.