Professional
Technical Writers Course

Professional Technical Writers Course

Мария Шапошникова — технический писатель в команде «Эхо». В этой статье она рассказывает о курсах для технических писателей и делится полезным опытом.

Мария Шапошникова

Technical Writer

Все “What’s New” или “Руководство пользователя”, которые вы читаете, когда уже все сломалось, пишутся техническими писателями. Самое сложное — это перевести язык технарей на человеческий, особенно когда ты сама немножечко (совсем) гуманитарий, а должна описать алгоритм или формулу так, чтобы такие же как ты (немножечко гуманитарии) поняли, как это работает.

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

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

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

Задания идут от простых к сложному. Сначала учишься писать деловое письмо, но очень быстро материал усложняется. Большая часть курса посвящена правильному написанию мануалов «от» и «до»: т.е. как описание всей функциональности продукта, так и описание FAQ.

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

Последнее задание — это написание технического отчета по выбранной теме.

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

Пример интерфейса xml редактора

Плюсы

  • Есть инструктор. Ты всегда можешь задать вопросы и попросить помощи в выполнении заданий.
  • Хорошая обратная связь: инструктор отвечает подробно и быстро, проверка заданий осуществляется за один, максимум два дня.
  • К каждому заданию дают комментарии, ты видишь свои ошибки. Благодаря этому полученная информация хорошо укладывается в голове.
  • Содержание курса: все по делу, от простого к сложному. Все подробно расписано и приведены примеры.
  • Бонусом к прокачиванию тех. писательства получаешь умение работать с xml редакторами, так как почти все задания пишутся в них.
  • Особенно полезна была часть про написание мануалов и FAQ

Минусы

  • Всего в курсе 5 заданий, и, начиная с третьего, они очень объемные, поэтому совмещать их и полный рабочий день крайне тяжело, а только выходных на выполнение не хватит. По идее, третье и четвертое задание можно писать в группе с кем-то, однако среди моих сокурсников были только те, кто жил со мной в слишком разных часовых поясах (США, Канада, Австралия), мне пришлось выполнять курс в гордом одиночестве.
  • На мой взгляд, курсы были бы эффективней на более раннем этапе работы, например, через полгода. Я же проработала уже полтора года и знаю многое из того, что там преподают.

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

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

Итак, несколько правил по написанию таких документов, которые показались мне наиболее полезными:

  • Прежде всего нужен четкий стайл гайд, и его надо придерживаться. К примеру, если вы прописали в вашем стайл гайде, что основное повествование ведется в настоящем времени, а не в прошедшем, то так и нужно делать. Это особенно полезно, когда на проекте не один, а несколько писателей, стайл гайд поможет сохранить единую структуру текста.
  • Все разделы должны быть названы единообразно, т.е. если в заголовках раздела у вас существительные, например, “Pricing functionality”, то остальные заголовки не должны быть названы в другом стиле, например, “Getting started with pricing” или “How to set up pricing”.
  • Если вы описываете процесс и вставляете в конце скриншот, иллюстрирующий, что должно получиться, то и в начале надо вставить скриншот того, что было «до», чтобы пользователь мог сравнить.


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

    Первый экран создания заказа

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

    Созданный заказ

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

Пример оформления раздела

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

Написание FAQ

    А вот FAQ лучше всего подготавливать по следующей схеме:

  1. Нужно понимать, что FAQ — это описание процесса. Здесь не может быть никаких подробных описаний, только ссылки на эти описания в другом разделе.
  2. В начале FAQ обычно идет только одно вступительное предложение, которое сообщает, что мы будем сейчас делать.
  3. После него идет нумерованный список действий.
  4. В конце FAQ показывается результат процесса, который уже не входит в нумерованный список.
  5. Наш FAQ готов, мы восхитительны.

Заключение

Курс интересный, но объемный. Лично для себя наиболее полезным считаю следующее:

  • Познакомилась с различными стандартами по оформлению мануалов, научилась работать в xml редакторе.
  • Хорошо уложилась в голове информация о том, как лучше составлять описание функциональности, а как описывать FAQ. Выяснилось, что я люблю добавить много информации «на всякий случай, а вдруг что», от такой учили безжалостно избавляться.
  • Ту часть курса, в которой расписывается подробно, какой стиль приемлем для технических текстов, а какой нет, я уже давала читать новому техническому писателю, когда она только пришла работать в компанию. Для новичков в профессии — это очень хорошо структурированный и доходчиво написанный материал.
Вакансии

Мы постоянно расширяемся, поэтому сейчас у нас открыто 8 вакансий.


Самара
Тольятти
8 ВАКАНСИЙ