Инженеры, лингвисты и работники завода — как открыть в себе технического писателя

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

Любой IT-проект — приложение, сайт, сервис — обвешан документами со всех сторон. Всё начинается с технического задания, продолжается пояснительными записками (если ваш главный заказчик — очень большой человек) и заканчивается программой испытаний. Эти документы создают технические писатели. Разобраться, написать и не сойти с ума могут только люди с определённым опытом и навыками.

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

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

Технический писатель Любовь Нужная думала, что будет работать с текстами восемь часов в день, а оказалось, прежде чем писать, нужно разобраться в продукте и побыть немного дизайнером, слегка разработчиком и чуть-чуть аналитиком. Разработка документа вообще похожа на решение головоломки.

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

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

В нашей компании (но так бывает не везде) важно, чтобы техписатель разбирался в ГОСТах. В KODE — это кунг-фу технического писателя, без которого не стать мастером.

Документация в IT-проекте бывает внутренней — для команды разработки, и внешней — для заказчика. Пишут её тоже по-разному:

Технические писатели работают по ГОСТам 19 и 34. ГОСТ 19 устанавливает требования к документации на программное обеспечение, ГОСТ 34 — на автоматизированные системы.

Чтобы написать документацию, которая полно и точно опишет всю систему, понадобится знание обоих: 19 устанавливает правила оформления, 34 — определяет структуру, виды и содержание создаваемых документов. Но даже точное следование ГОСТам не означает, что к написанному документу не будет правок.

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

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

Если убрать техписателя из IT-проекта — ничего не случится, приложение сделают и без него. Но сдать проект заказчику (читай: получить деньги) никогда не получится. Хотя казалось бы, ну кто читает эти ваши документы?

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

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

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

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

Техписатель должен понять, как будет работать приложение, и объяснить это заказчику. Для этого он изучает гору информации, а потом пишет документацию (не редактирует то, что принесли коллеги, а пишет с нуля).

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

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

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

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

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

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

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

В тестовом мы смотрим, чтобы текст был конкретным и однозначным. Вот примеры:

❌ Чтобы закрыть окно, нажмите на соответствующую кнопку.

✅ Чтобы закрыть окно, нажмите на кнопку «Закрыть».

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

Давайте разберём ещё один пример — из реального ТЗ: «Режим работы приложения должен обеспечить максимальное удобство и комфорт пользователя».

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

Пишите в комментариях свои варианты, как переформулировать такое предложение в ТЗ. А посмотреть вакансию для технического писателя можно на нашем сайте.