Привет! Я Катя, руководитель группы технических писателей в Ozon. Сейчас нас уже 9 человек и целая платформа документации, но коллеги всё ещё не всегда понимают, чем мы занимаемся.

Из непонимания появляются запросы вида: “Хотим себе собственного техписателя в команду, но не знаем, чем именно он будет заниматься”. В итоге команда подстраивается под тренды и заводит себе документацию, но через пару месяцев оказывается, что доку не читают, а техписатель плавно превратился в аналитика.  

Поэтому пришло время делиться опытом и рассказывать о каких-то концептуальных штуках ? :)

Кто вообще такие технические писатели?

Встречала разные ответы, от "ребята, которые пишут никому не нужные талмуды по ГОСТам" до вполне близких к моей реальности определений. 

В Ozon технические писатели занимаются глобально тремя направлениями: 

• пользовательской документацией (Помощь, База знаний, FAQ), 

• документацией внешних API, 

• описанием внутренних систем — от онбордингов до сложных архитектурных взаимодействий. 

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

Ещё к нам часто приходят просто за качественными текстами — для лендингов, постов, обучающих курсов. Нам интересно, и мы не отказываем, но не могу сказать, что это попадает под именно техническое писательство. 

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

Технические писатели описывают, как устроены какие-то системы и как с этими системами работать. Это может быть пользовательская инструкция по оформлению возврата или схема взаимодействия методов API — но это всегда ответ на вопрос "как что-то сделать". 

Как понять, что пора заводить технического писателя?

Если у вас есть продукт, которым пользуется кто-то снаружи — час пробил. Даже если "снаружи" сидит в соседней команде. Любое погружение посторонних в ваш продукт или проект уже подразумевает документацию, а, следовательно, и позицию технического писателя. 

 Но есть нюансы: 

1. Документации нет и это не создаёт никаких реальных проблем — техписатель не нужен.  

2. Документацию уже кто-то пишет и ему проще делать это самостоятельно, чем объяснять техписателю — у вас уже есть технический писатель, только называется он "инициативный разработчик" или "ответственный аналитик". 

3. В системе часто что-то меняется — чаще, чем приходится систему кому-то объяснять — проще рассказать на словах, чем поддерживать все изменения. Часто можно сказать: "Ребята, сейчас используем вот эту штуку, документация на официальном сайте", а не расписывать подробные инструкции, которые через пару месяцев уже будут не нужны. 

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

Где искать технических писателей и как оценивать кандидатов?

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

Кто-то приходит из лингвистов и филологов со стремлениями уйти в аналитику или разработку. Я стараюсь искать (особенно стажеров) по техническим вузам; там довольно много ребят, осознавших, что кодить 24/7 — не их стезя. А вот что-то рядом, но чуть гуманитарнее — наш идеальный кандидат. 

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

Если это ваш первый технический писатель на проекте, дайте что-то про описание процесса или архитектуры. Оцените полноту описания, структуру и термины, которые использует кандидат. Прочитайте Ильяхова или подпишитесь на рассылку о текстах, чтобы примерно понимать, где хорошо, а где не очень. Но важнее, чтобы устраивало конкретно вас и попадало в формат компании, чем полное соблюдение концептов информационного стиля и 10 баллов по Главреду. 

Как выстроить процесс?

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

 В общем виде документация создаётся по такому сценарию: 

1. Определить цель документа и его аудиторию.  

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

3. Понять, кому и по каким темам можно задавать уточняющие вопросы — найти экспертов и договориться о формате работы с ними. 

4. Наполнять документ и параллельно отдавать на вычитку коллегам-техписателям и экспертам. 

5. Финализировать структуру и тексты — обязательно отдать кому-то на вычитку и после этого презентовать заказчику. 

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

Ещё один тонкий момент — что именно может править заказчик. Оговорите это сразу, при постановке задачи: важно, чтобы заказчик не пытался переписать ваш текст согласно своему субъективному взгляду. Факты и термины — да, тут он эксперт, но вкусовщину надо учиться фильтровать. 

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

Моя формула найма: 1.5 техписателя на проект. За половинку может считаться стажер или техписатель из другой команды — так есть и с кем экспертизой обменяться, и кто на время отпуска-болезни подхватит проекты. 

Нужен ли вам техписатель: чеклист 

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

• Кому может понадобиться документация к моему проекту? Моим же разработчикам, внешним пользователям? 

• Как проблема отсутствия документации решается сейчас? Система понятна и без дополнительного описания? Может, кто-то уже снял обзор по этой теме на YouTube? 

• Если документация всё же нужна, в каком виде её будет удобно потреблять? Всплывающие подсказки, вебинары, отдельный URL с базой знаний? 

• Чем будет заниматься технический писатель, когда напишет документацию? Продолжит её актуализировать? Перейдёт на соседний проект? 

Начинайте поиски технического писателя, только если у вас сложилась общая картинка о месте документации в вашем проекте. Отнеситесь к документации как к полноценному продукту. 

Что дальше?

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

И, конечно же, ждать подробностей в следующих статьях ?:)