Мы начинаем серию публикаций с тезисами выступлений 2014 года. Сегодня речь пойдет о докладе «Особенности создания веб-документации для пользователей» с Гипербатона, прошедшего в рамках конференции Translation Forum Russia в Екатеринбурге.
Как писать, чтобы ответить на вопросы пользователя
Основная проблема пользовательской веб-справки ― ее ориентированность на функциональные возможности продукта, а не на пользователя. Как результат: читатель не может найти в документации ответ на свой вопрос. Наш подход к решению этой проблемы до банальности прост ― справка должна (буквально) состоять из вопросов пользователей и ответов на них.
Откуда мы берем вопросы?
- Смотрим, с какими проблемами обращаются в службу поддержки.
- Анализируем данные в Яндекс.Метрике ― узнаем, по каким поисковым запросам пользователи приходят в Помощь.
- Если сервис новый и пользователям еще не знаком, вопросы формулирует команда сервиса. Также сервис тестирует разработчик документации и описывает возможные пользовательские кейсы.
На сформулированные вопросы мы стараемся дать короткие емкие ответы. Если формата «вопрос-ответ» недостаточно, готовим пошаговые иллюстрированные инструкции. А для наших профессиональных сервисов создаем раздел «Быстрый старт», в котором рассказываем, что нужно сделать для начала работы.
Как поддерживать качество документации
Раньше документацию в Яндексе писали специалисты службы технической поддержки и менеджеры сервисов ― без единого подхода к данному процессу каждый делал это по-своему. Сегодня поддерживать единообразие многих документов для разных сервисов нам помогают следующие правила и инструменты:
- За каждым сервисом закрепляется один-два ответственных технических писателя. Такой подход позволяет авторам глубоко погрузиться в тему, исключить дублирование контента и оперативно поддерживать его актуальность.
- В своей работе мы используем внутренние руководства по языку изложения и оформлению иллюстраций ― в них регламентируются основные моменты, разнобой в которых будет заметен или может помешать пользователю. Например, типовые обороты для описания интерфейса, использование технических терминов, оформление ссылок и т. п.
- Практически для каждого инструмента у нас есть собственные шаблоны, которые мы применяем, чтобы не изобретать «велосипед» при выполнении типовых действий.
- В работе над текстами руководствуемся несколькими принципами:
- Писать коротко и ясно.
- Разъяснять только неочевидное.
- Формулировать вопросы как пользователь.
- Вначале написать, что и зачем делать, потом объяснить ― как.
- Структурировать текст с помощью катов, табов, подразделов.
Как упростить поиск по документу
Вот несколько способов упростить поиск по документу:
- Сделайте хорошую посадочную страницу, чтобы сформировать общее представление о вашем продукте.
- Создайте отдельную страницу для каждой темы или группы связанных вопросов.
- Используйте мини-оглавление для быстрого ориентирования на странице.
- Разместите список полезных ссылок на статьи, к которым пользователи обращаются чаще всего или которые не включены в документ, но могут дополнить его.
- Используйте двойные заголовки (тег <navtitle>) ― укажите короткий емкий заголовок в содержании, чтобы не перегружать его, а на странице напишите более подробный заголовок, который будет соответствовать запросу пользователя.
- Укажите ключевые слова для каждой страницы (тег <keyword>) ― это те поисковые запросы, по которым пользователь приходит в вашу веб-справку.
- По возможности поддерживайте адаптивную верстку для десктопных и мобильных платформ
Что нужно учитывать при подготовке текста к переводу
Сервисы Яндекса доступны в разных уголках планеты. И в каждой стране присутствия мы работаем так, как будто мы местные. Чтобы «говорить» с пользователем на одном языке, в документации:
- Используем примеры и иллюстрации с местными географическими названиями.
Русская версия на домене RU
Русская версия на домене UA
Украинская версия на домене UA - Указываем цены в местной валюте.
- Учитываем различия в функциональности сервиса. Например, турецкие пользователи ищут товары по-другому, поэтому в Турции у сервиса Яндекс.Маркет иные алгоритмы работы, а значит и другая документация.
- Публикуем документацию для каждого региона на отдельном домене. Если в стране есть несколько государственных языков или широко распространен второй, то публикуем документацию на всех этих языках. Например, для Турции справка публикуется на турецком и английском языках.
Пользовательская справка содержит разную информацию для разных стран. Чтобы не запутаться при ее написании, обновлении и переводе, а также не дублировать одинаковые части, мы используем следующий подход:
- Пишем полную версию на русском языке. Она содержит все возможные варианты текста для разных доменов (стран) и языков, в том числе те, которые на русском публиковаться не будут.
- Делаем разметку в тексте, с помощью которой указываем, для каких языков и доменов (стран) написан каждый фрагмент.
- Отдаем на перевод отфильтрованную версию текста. В нее попадают только те фрагменты, которые нужны на конкретном языке. Фильтрация выполняется автоматически. После перевода получаем полную версию текста на русском языке и переведенные на разные языки версии для других стран.
- Перед публикацией снова выполняем фильтрацию и получаем несколько комплектов документации для разных доменов с нужным набором языков.
Разметка текста
Текст на домене RU
Минимальная сумма заказа в Яндекс.Директе составляет 300 рублей.
Текст на домене UA
Минимальная сумма заказа в Яндекс.Директе составляет 81 грн.
Мінімальна сума замовлення в Яндекс.Директі становить 81 грн.
В заключение
Еще раз перечислим основные приемы, помогающие нам улучшить документацию для пользователей:
- Мы пишем, чтобы ответить на вопросы пользователей.
- При создании текста следуем принципу «мало букв — много смысла».
- Структурируем тексты, чтобы упростить поиск по документу.
- Стараемся говорить с пользователем на одном языке.