— Кем ты работаешь? — спросила меня однажды моя знакомая.
— Техническим писателем.
— Техническим... писателем, — повторила она задумчиво. — Бывает еще такая музыка — в стиле «индастриал».

До того как я стала техписом, большинство моих друзей и не подозревали о существовании такой профессии. Кажется, кому придет в голову набрать в поисковой строке «технический писатель»? Некоторое количество таких запросов, тем не менее, нашлось.

Итак, если коротко:

Большая часть запросов (всего их было около 1300), наверное, похожа на запросы о любой другой профессии: интересуются вакансиями, средней зарплатой, обязанностями и требованиями к техническим писателям. Те, кто еще не стал техписом, спрашивают о курсах и обучении. Работодатели ищут тестовые задания, расценки и недоумевают, как правильно сделать запись в трудовой книжке.

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

А какие запросы задают о вашей профессии? Узнать об этом можно с помощью специальных сервисов, например, Подбор слов от Яндекса.

Мой начальник периодически напоминает мне, что нет такой профессии — «технический писатель». Я обычно не спорю. Нет, так нет.

Про себя я думаю, что раз в русскоязычной Википедии есть приличная статья про технических писателей, значит, можно считать, что профессия есть. Более того, в англоязычной Википедии нашлась статья про отдельный класс технических писателей — которые описывают API («АПИсатели» по-нашему). АПИсатель — это как раз про меня.

Кроме общих фраз, дающих АПИсателю приятную возможность самоидентифицироваться, в статье можно найти еще и адекватные требования к квалификации: http://en.wikipedia.org/wiki/API_Writer

.

Когда чем-то занимаешься долго, не замечаешь изменений. Просто все меняется постепенно, а кажется, что так было всегда.

Вот и у нас такая же история.

Весной 2007 года (я тогда пришла в Яндекс) у нас была маленькая группа техписателей. Занимались мы только внутренней документацией. Писали на русском языке. Использовали три или четыре инструмента для разработки документации.

А сейчас нас уже много. Мы отвечаем за всю документацию: техническую и пользовательскую, внутреннюю и внешнюю. Переводим ее на несколько языков. У нас постоянно появляется что-нибудь новенькое, чего мы не делали раньше, и мы ищем новые подходы и инструменты. Теперь в нашем арсенале большой набор разнообразных средств. С их помощью можно решать практически любые задачи документирования.

О наших орудиях производства я недавно рассказывала на вебинаре «ТехДок 2104: Софт». Время выступления было ограничено, поэтому доклад получился обзорным. Из него вы узнаете, какие программные продукты и технологии мы используем. А также познакомитесь с некоторыми приемами и подходами, которые сделали нашу работу удобнее.

Задавайте вопросы!

Разработкой документации технической интересуетесь? Документации переводы делаете? Поставить как процесс, узнать хотите?

«Гипе́рбатон» — технических писателей конференция для вас. А если говорить серьезно, то 24 мая мы ждем всех на нашей новой конференции.

На Гипербатоне мы обсудим общие вопросы документирования, поговорим о программной документации, локализации и переводе, затронем тему оценки документов. Подробная программа будет опубликована в ближайшее время.

В мероприятии примут участие специалисты Яндекса, «Лаборатории Касперского», Microsoft, ABBYY и других компаний. Так же планируется много активностей в рамках конференции.

Участие бесплатное, но необходимо зарегистрироваться. Количество мест ограничено. Регистрация заканчивается 22 мая в 18:00 по московскому времени.

Ссылка на регистрацию.
Ссылка на мероприятие.

Программа конференции будет опубликована в ближайшее время. Следите за новостями в наших каналах Events:

 Twitter 

 Facebook 

 Вконтакте 

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

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

Профессор Джозеф Уильямс начинает свою книгу Стиль. Уроки ясности и изящества (англ. Style. Lessons in Clarity and Grace) с цитаты:

Знайте, что хотите сказать, и говорите об этом настолько ясно, насколько это возможно. Это единственный секрет стиля.

Мэтью Арнольд

Книга не заканчивается на этом совете, так как следовать ему сложнее, чем кажется. В рубрике «Стиль» мы попытаемся адаптировать уроки этой книги к русскому языку и применить их к документации Яндекса. Если все получится, то мы увидим, как сделать текст легче и яснее в заранее определенных рамках содержания.

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

Добрый день!

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

На Гипербатоне вы узнаете:

• кто и как становится техническим писателем; 
• как начать документировать API с нуля;
• как создается контент для сайтов MSDN и TechNet;
• как провести экспертизу текста в интерфейсе;
• как использовать инструменты веб-аналитики для оценки качества документов;
• как правильно выстроить процесс локализации разных типов документов.

Для тех, кто не сможет попасть будет организована онлайн-трансляция на странице мероприятия. У нас появился хештег, по которому вы можете задавать нам вопросы. Наш хештег: #yadoc

Напоминаем о том, что участие бесплатное, но необходимо зарегистрироваться. Количество мест ограничено. Регистрация заканчивается 22 мая в 18:00 по московскому времени. 

Ждем всех 24 мая в московском офисе Яндекса на первом Гипербатоне!

Текст может рассказывать о самых простых концепциях и фактах, но оставаться неясным для читателя. Почему это происходит?

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

Список можно продолжать. Но в конечном счете практически все эти причины можно свести к одной простой ошибке: автор пишет для себя, а не для читателя; пишет подробнее о том, что непонятно ему, а не читателю; разрабатывает структуру текста, в которой удобно писать, а не в которой удобно читать. Пока мы пытаемся отвечать каким-то внутренним стандартам, вместо того, чтобы отвечать потребностям пользователей, клиентов и коллег, хорошие тексты получаются только случайно.

Жесткие правила никому не помогут писать яснее. Человек, который не понимает, о чем и зачем он пишет, не сможет создать элегантный и прозрачный текст. Но те, кто ясно видит свой предмет, могут писать яснее, руководствуясь простыми принципами, которые мы рассмотрим в этой рубрике.

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