В Яндексе, как и в других крупных компаниях, очень много разных подразделений. Большие и маленькие, всем известные и такие, о работе которых пользователи сервисов Яндекса задумываются редко. Одно из таких подразделений — служба разработки технической документации.
Техническая документация — это инструкция или справочник, объясняющий, как работать с сервисом или как он устроен. Вы наверняка сталкивались с технической документацией — если не в разделе «Помощь» на Яндексе, то в виде инструкции к стиральной машине. От понятности и грамотности технической документации зависит удобство работы со многими сервисами. Например, документация позволяет владельцам магазинов узнать, как правильно зарегистрировать свой магазин на Яндекс.Маркете, а клиентам Яндекс.Директа помогает правильно составить текст рекламного объявления.
Кроме «Помощи» для пользователей у Яндекса есть документация для разработчиков и других технических специалистов – описания технологий, руководства и справочники по использованию API (программных интерфейсов) сервисов Яндекса. Например, документация на технологию БЭМ или API Карт. Также много внутренней документации, предназначенной для сотрудников Яндекса. Без нее вся информация хранилась бы только в голове у людей, и им пришлось бы бесконечно рассказывать всем заинтересованным, как протекает тот или иной процесс или как правильно реализовать ту или иную функцию.
Служба разработки технической документации существует в Яндексе с сентября 2006 года. Это одно из постоянно развивающихся подразделений. Сейчас в нашей службе работает уже 25 технических писателей. Четверо специализируются на написании инструкций для пользователей, пятнадцать – на разработке документации для разработчиков, а остальные делают и то, и другое.
В этом году мы выступали на конференции YaC с рассказом о нашей работе. Когда мы готовили этот доклад, нам пришла в голову идея провести конкурс для технических писателей. В качестве конкурсного задания мы решили предложить переработать какой-нибудь широко известный документ. Перебрали тексты законов, кодексов, правил и остановились на Правилах дорожного движения. ПДД, как и все правовые документы, написаны сложным языком, который больше подходит для однозначной трактовки в судебных разбирательствах, хотя должны быть понятны миллионам людей. Поэтому задание по переработке статьи ПДД как нельзя лучше позволяет техническому писателю применить свои профессиональные навыки в новой области.
Полученные работы оценивались по тем же критериям, которые мы используем при проверке своей документации:
- Структура. В хорошо организованном документе легко искать нужную информацию.
- Язык изложения. Справочники и руководства не читаются как романы. В технических текстах важно ясно и коротко донести смысл. В идеале каждое предложение должно быть понятно с первого прочтения.
- Полнота. Важно не потерять нужную информацию. При этом не стоит путать полноту с избыточностью.
- Точность. Информация должна быть изложена фактически точно и технически грамотно.
- Полезность для целевой аудитории. Документ обязан отвечать на вопросы тех пользователей, для которых он предназначен.
Первое место заняла Наталья Воронцова из Москвы. Второе место разделили Инна Якименко из Санкт-Петербурга и Егор Абраменко из Барнаула. Работы Инны и Егора очень разные, и каждая хороша по-своему, поэтому мы решили присудить второе место обоим участникам.
Выполненные работы мы не публикуем. Но авторы вольны сделать это сами на любых площадках.
Светлана Каюшина, руководитель службы разработки технической документации