Professional Technical Writers Course

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

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

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

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

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

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

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

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

Плюсы

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

Минусы

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

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

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

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

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

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

  

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

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

  

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

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

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

Написание FAQ

Заключение

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

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