Почему технический писатель должен быть Шерлоком Холмсом

Мы уже писали о профессии технического писателя: рассказывали, какие навыки нужно развивать и какие полезные материалы читать. А сегодня расскажем, как работают техписы в Яндекс Крауд — и почему руководства продуктов Яндекса считаются такими понятными.

Крауд — это внутренний сервис для решения бизнес-задач команд Яндекса. Его сотрудники работают удалённо и помогают решать бизнес-задачи для разных команд и продуктов компании. Одна из таких задач — написание технических документов. Техписы из Крауд подготовили документацию для Директа, Практикума, Карт, Алисы и других сервисов Яндекса.

Какие требования к документации существуют

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

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

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

Например, нам нужно описать автобус и то, как работает его колесо. Если мы положим информацию в раздел «Знакомство с ПДД», пользователь никогда в жизни её там не найдёт. Поэтому хорошая документация должна быть логично структурированной, чтобы пользователь открыл и сразу понял, где искать ответ.
Изабелла Оз, технический писатель в Яндекс Крауд

Соответствие требованиям. Если в ТЗ указано «Описать автобус так, чтобы понял пятилетний ребёнок», техпис понимает, что не нужно описывать процесс работы двигателя. Важнее рассказать о полезном действии автобуса, о доставке людей и устройстве салона. А если в задании сказано, что эту информацию будет читать водитель автобуса, — наоборот, стоит описать, как работает двигатель и в каких случаях происходят поломки.

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

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

• Эмпатия. Здесь важно сконцентрироваться на общем восприятии текста и его понятности. Техпис представляет, что сам ищет информацию, чтобы расположить её именно там, где будет искать пользователь.

Как устроена работа техписов в Яндекс Крауд

Технические писатели в Яндекс Крауд делятся на исполнителей, которые непосредственно пишут тексты, и менеджеров, которые обрабатывают заказы и передают их исполнителям.

Писатели в Крауд работают по системе свободного выбора. Они видят пул задач и выбирают те, что им нравятся. Такая система позволяет техписам фокусироваться на конкретном типе задач — например, при желании описывать только новые фичи. Однако чёткого деления по специализации нет. Большинство техписателей могут писать о чём угодно.

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

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

Задача технического писателя — не только изучить исходники, но и копнуть глубже. Важно понять, с чем у пользователей могут быть проблемы, и описать это в документации. Конечно, предусмотреть всё невозможно и никто не будет читать про каждую кнопочку. Поэтому мы пытаемся выяснить, что самое критичное может возникнуть, и это описать.
Изабелла Оз, технический писатель в Яндекс Крауд

Кому стоит идти техписом

В первую очередь техпис — это грамотный автор. Он прекрасно знает русский язык, чувствует и понимает текст. Ещё технический писатель в Яндекс Крауд должен быть любознательным и не бояться больших объёмов новой информации. Это своего рода Шерлок Холмс, который должен разгадать, чего хочет пользователь, что ему может быть непонятно и как решить его проблемы.

У меня за три года работы ни разу не было скуки: всегда приходят новые вызовы. Это не монотонная работа, когда ты сидишь и что-то набираешь, как на печатной машинке. Надо быть готовым к загадкам, как в бюро Шерлока Холмса.
Изабелла Оз, технический писатель в Яндекс Крауд

Сервисы Яндекса постоянно развиваются, и возникают новые задачи для техписателей. Каждый день они работают с разными текстами. Это и создаёт драйв на рабочем месте.

К образованию требований нет. Техписами в Яндекс Крауд становятся разработчики, филологи, преподаватели русского языка.

Я специалист в международных отношениях и пришла к техническому писательству довольно случайно. Я училась в магистратуре, и меня интересовал копирайтинг, языки программирования и графические редакторы. Как объединить всё это в одну профессию, я не представляла, пока не наткнулась на рекламу Академии Гипербатона в соцсетях. Тогда подумала, что в профессии технического писателя можно совместить все мои увлечения.
Изабелла Оз, технический писатель в Яндекс Крауд

Чтобы попасть в команду Яндекс Крауд, стоит отслеживать вакансии. Они появляются по запросу мини-редакций сервисов, когда им требуется технический писатель для выполнения определённых задач. Новый исполнитель также имеет доступ к общему пулу задач, а впоследствии может вступить в редакции других сервисов.

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

Что такое конференция Гипербатон

Технический писатель в Яндекс Крауд не только пишет тексты и общается с разработчиками, но и постоянно совершенствует свои навыки и обменивается профессиональным опытом с коллегами. Для этих целей в Яндексе создали Гипербатон — конференцию по разработке технической документации. Сейчас Гипербатон закрыт, но записи мероприятий доступны для просмотра.

Вот несколько хороших материалов:

• Технические писатели с ударением на первом слове. Как искать и взращивать квалифицированных специалистов по документации — Семён Факторович (2016);

• DITA в Яндексе: почему и как — Алексей Миронов (2017);

• Новый взгляд на документирование API и SDK в Яндексе — Андрей Поляков и Юлия Пивоварова (2018);

• Как измерить качество документации — Светлана Каюшина, Юрий Никулин, Антон Литвинов (Мини-Гипербатон, 2018).

С чего начать написание документации: советы от техписа

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

Обратитесь к коллегам. Для техписов 15-минутное обсуждение может быть продуктивнее 10-часовой одиночной работы. Попросите руководителя подсказать вам направление или посоветуйтесь с коллегами. Обмен опытом очень полезен, особенно когда вы работаете из дома и нет постоянного личного контакта.

Соберите исходники. Может быть, у вас есть видео, в котором рассказывают о сервисе, или комментарии в 3450-й строке кода?

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