Хотела начать текст с шутки про то, что раз инструкции никто не читает, то и писать их не обязательно. Однако 14 лет работы в IT-сфере доказывают, что это всё же довольно глупая шутка. В современных компаниях (не только в IT, но и особенно в IT!) на документации завязаны практически все процессы от проектирования ПО и ведения бэклога до эксплуатации и поддержки пользователей. Люди со стороны часто не догадываются, что в командах кроме суровых разработчиков, дотошных тестировщиков, внимательных сисадминов, осторожных безопасников и продвинутых девопсов трудятся технические писатели. Как правило, они одновременно суровые, дотошные, внимательные, осторожные и продвинутые, потому что именно на них лежит ответственность как за внутреннюю документацию, так и за корректные, грамотные, лаконичные и точные инструкции для пользователей. И писать желательно без девяти прилагательных в одном предложении, как строчкой выше ?

Сегодня поговорим об этих ребятах, о профессии, о людях в ней и о том, стоит ли войти в айти именно через вакансию техписа?

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

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

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

Московкина Анастасия

X5 Tech, Teamlead

Профессия технический писатель за последнее время сделала огромный шаг вперед сразу в трех направлениях:

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

• Развитие инструментов. Отрасль IT никогда не стояла на месте, а в последние годы это сильно сказалось и на основном инструменте технических писателей. Про docs-as-code не слышал, наверно, только ленивый. Все больше компаний ведут свою пользовательскую и проектную документацию в этой концепции. При этом появляются новые инструменты, которые помогают облегчить входной порог, используя удобные визуальные редакторы.

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

Итак, чем занимается технический писатель в компании?

• Прежде всего он собирает и анализирует информацию о продукте, интерфейсе, паттернах и сценариях использования, среде функционирования и прочем. Этот массив информации в дальнейшем послужит основой для создания технической документации (думаю, не нужно объяснять, что это не одни только мануалы). Причём сбор осуществляется двумя путями: с одной стороны, специалист сам изучает продукт и фиксирует необходимые моменты, а с другой, он опрашивает разработчиков (и уж простите, порой просто «трясёт» информацию из вечно занятых коллег). 

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

• Готовую документацию часто передают в тестирование — тестировщики проверяют её точно так же, как и всё остальное: с тест-кейсами, багами и прочим. В свою очередь, технический писатель вносит исправления и проверяет, чтобы они соответствовали остальному тексту. 

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

Ушакова Екатерина

руководитель отдела технических писателей в Ozon Tech

О себе: деловой телеграм
Блог на Хабре

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

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

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

Какую документацию готовит техпис? 

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

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

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

• UX-тексты (подсказки, пункты меню, и т. д.) — вообще это удел UX-писателя, но в большинстве компаний… вы поняли ?

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

• Технические переводы с русского на иностранный и обратно — чаще всего именно задача техписа, но здесь есть нюанс с владением языками, поэтому нередко ему помогают переводчики (особенно в мультиязычных компаниях).

Теодора Малевинская

Держатель профессии «технический писатель» в Тинькофф

О себе: Строю техписательские процессы для разработчиков, собираю редакции, развиваю профессиональное сообщество в компании и вне. Веду блог: deus_theos
Блог на Хабре

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

Исследование 1

В 2016 StackOverflow провёл исследование среди разработчиков о том, с какими проблемами они сталкиваются в работе. Вторая по популярности — "скудная документация”. Так проголосовали 34,7% из 100%. Источник.

Исследование 2

В 2017, 2018, 2022 и 2023 годах StackOverflow провёли новые исследования и выявили, что для 80–90% разработчиков документация — основной источник, по которому они изучают технологии. Исследователи делают вывод: «Это показывает как важно для компаний иметь хорошо написанную документацию».

Источники: 2017, 2018, 2022 и 2023. 

Исследование 3

Nintex проводили исследование о самых неэффективных процессах в ИТ-компаниях. Ожидаемо — большая их часть связана именно с документацией:

• 59% респондентов из 100% — решение технических проблем. Я сама наблюдаю, что часто такая проблема бывает из-за того, что какие-то ошибки или процессы не описаны в документации.

• 49% респондентов из 100% — трудность с поиском документов.

• 55% респондентов из 100% — нет инструментов (или доступа к ним) и документации для работы.

• 43% респондентов из 100% — нет документации для онбординга.

Источник

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

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

Что должен знать и уметь технический писатель? 

Это тоже зависит от компании, продукта и существующих задач, но мы с вами обратимся к Хабр Карьере и посмотрим, что требует рынок.

• Знание нормативных документов (ГОСТ 34, ГОСТ19, ГОСТ 2.105, ISO) и других стандартов оформления технической и проектной документации на ПО. Есть почти во всех вакансиях в той или иной мере. В любом случае знание ГОСТ сильно облегчает работу и дарит навык структурирования.

• Навыки сбора и анализа информации.

• Навыки сбора и анализа, а также описания требований — да, с требованиями техническим писателям приходится работать часто, и там есть серьёзные нюансы сбора, агрегации и «просеивания» собранной информации. 

• Способность работать (структурировать, перерабатывать) с большими объёмами информации — и с каждым годом всё больше.

• Аккуратность, внимание к деталям.

• Умение писать легко и понятно — пользователи разные, и информация должна быть доступная каждому.

• Отличное знание русского языка.

• Знание английского языка — как значительное преимущество, а часто и строго обязательное требование.

Мария Смирнова

Руководитель группы пользовательской документации

О себе: деловой телеграм

Есть расхожая фраза про то, что технические писатели — это «переводчики с разработческого на пользовательский». При всей её заезженности и радикальности я скорее склонна с этим тезисом согласиться. Не в последнюю очередь из-за того, что я сама не только технический писатель, но и переводчик.

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

Как говорила матерь всех переводчиков Нора Галь, «переводить надо не слово, не букву, а дух и смысл». И я верю в то, что этот принцип должен лежать в основе любой работы с текстом, особенно в работе технического писателя. С чем бы вы ни работали, думать о смысле — лучшее, что вы можете сделать для себя, для читателя и для заказчика. Это избавит вас от многих проблем и поможет решить большинство возникающих в работе вопросов. И, конечно же, не только сделает ваш «перевод на пользовательский» полезным, но и заставит его звучать нативно.

• Знание Markdown, LaTeX (формулы), HTML, CSS, Wiki-разметки — у большинства компаний есть свои правила и стандарты организации хранения и обработки технической документации, там целый зоопарк технологий. 

• Хорошее владение IT-терминологией, погружение в IT-тематику.

Как плюс в ряде компаний: умение читать код, понимание работы СУБД, навыки работы в графических редакторах (диаграммы, схемы, включая UML и BPMN). Действительно, техписам нередко приходится добавлять к документации схемы, графики, красивые таблицы и другие графические элементы.

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

Анастасия Клещенок

руководитель группы технической документации

Я работаю в небольшой команде технических писателей в Ozon. Наша команда трудится на благо одного департамента разработки. В департаменте 3 направления — у каждого свой техпис. Он помогает разработчикам со всеми типами документов.

Большой плюс такой позиции — разнообразие задач. Можно побыть в роли тестировщика, если редактируешь текст новой фичи, или менеджера, если внедряешь новый процесс для команды. Мы работаем с онбордингами для новичков, статьями про сервисы и ML-модели, API, release notes, пользовательскими инструкциями для внутренних инструментов. Интервьируем держателей знаний и пишем с нуля, доводим до готовых статей черновики разработчиков, вычитываем статьи коллег, помогаем оформлять тексты для интерфейсов и автодокументации.

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

Хорошая новость: чтобы работать техписом в команде разработки, необязательно иметь техническое образование. Достаточно желания разбираться в новом материале и работать с текстами.

Личные качества технического писателя

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

Кирилл Наумов

руководитель группы документации для разработчиков Ozon Tech

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

Я отучился год на журфаке, а потом перешел в вышку на менеджмент. Оба образования мне пригодились, потому что со временем я стал лидом.

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

Можно сказать, что прямо вот пишет технический писатель значительно меньше, чем собирает, анализирует, общается, уточняет. Очень дипломатичная профессия, в общем :-) 

Вопросы, которые могли остаться

Разве не лучше, если писать будут разработчики?

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

А если технический писатель ошибся?

Документация проходит контроль качества в отделе тестирования, как и весь комплекс программного обеспечения или инженерных решений. Однако всем свойственно ошибаться — и здесь уже компания оценивает критичность ошибки и выстраивает модель безопасности технической документации (например, неправильно описанная функция в ERP-системе может не повлечь урон, а вот ошибка в мануале к банковскому или инженерному ПО может стоить слишком дорого).

Технический писатель — это технический или писатель?

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

Каков путь развития?

Можно вырасти в тимлида техписов, можно уйти в управление, при желании явно видится переход в аналитику, тестирование, поддержку, разработку. Всё зависит от желания и уровня навыков. К слову, технические писатели довольно неплохо зарабатывают (сеньоры могут получать даже около 250 тыс. руб., джуны «разбегаются» от 45 до 75 тыс. руб., что местами побольше, чем у тестировщиков). 

Что там с копирайтерами?

Копирайтер пишет разные тексты для нужд компании: hr, pr, рассылки, реклама, буклеты, тезисы, статьи и многое другое.

UX-писатель (редкий зверь во многих IT-компаниях) — сочетает в себе навыки копирайтера и дизайнера. Более динамичный специалист, который пишет тексты для интерфейса. Чаще всего это одна из ипостасей технического писателя.

При этом без дополнительного обучения копирайтер и UX-писатель техписа не заменит, а вот техпис заменит всех. 

Хорошая статья о технических писателях из первых рук.

Теодора Малевинская

Держатель профессии «технический писатель» в Тинькофф

Собрала статьи, которые я обычно показываю знакомым айтишникам:

• Моя статья о том, как разработчику быстро привести в порядок базу знаний

• Как с нуля собрать статический генератор сайтов и задеплоить его на GithubPages — часто кидаю начинающим, чтобы они собрали такой сайт для своего портфолио.

• Как писать документацию на английском.

• Как изнутри выглядит документация docs as code  — хорошая вводная для начинающих..

• Серия статей о макросах Confluence. Хоть это и не самый современный инструмент для техписателей, многие активно его используют.

• Статья о подходе «collaborative documentation».

??✍️ А ещё «Подготовка технической документации» — это самая уникальная номинация за историю «Технотекста», потому что она была предложена не организаторами, не компаниями, а самим сообществом! 

Напоминаем: конкурс продлён до 14 апреля. Вы успеваете подать заявку.  

Теодора Малевинская

Держатель профессии «технический писатель» в Тинькофф

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

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

Ну и приятная новость в самом конце — инициативу сообщества не могло не поддержать издательство «Питер», которое подарит трём победителям книгу с намёком на то, что техпис в IT — больше, чем техпис ;‑)