Зачем нужны технические писатели

Текст как призвание

Уже много лет я работаю техническим писателем в крупной IT-компании. До этого мне приходилось заниматься и тестированием, и программированием, и преподаванием, затем больше пяти лет отработал ведущим бизнес-аналитиком. Но я вернулся в писатели, и в этой статье я расскажу, почему.

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

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

Текста больше, чем кода

— Кто за сутки до отправки заказчику во всей инструкции заменил manual на manul?!

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

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

В общем, текстов хватает. Так зачем же тогда в самом конце разработки нужен ещё и технический писатель? Почему всех этих документов недостаточно для того, чтобы дать ответы на основные вопросы заказчика и пользователя: как работает система и как её настроить?

Будем разбираться.

Разработчики должны писать код, а не текст

«Условие, что поле PART должно быть не пустым, обеспечивается целостностью процесса, заполняющего это поле, и не обеспечивается отдельным ограничением Oracle типа NOT NULL для обеспечения максимального быстродействия при изменении данных таблицы».Из внутренней документации проекта

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

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

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

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

Стройная система подпорок и противовесов

Хогвартс напоминает любой IT-проект, который разрабатывается долгое время. Древние баги, нигде не прописанные фичи, несовместимости, куча сдерживающих этот ужас костылей и несколько программистов, которые даже не хотят лезть в неведомые глубины и гордо называют их «школьными традициями».bash.im

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

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

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

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

Внутренние документы по системе, порождённые в процессе разработки, представляют для пользователя неразрешимую головоломку. Без пользовательской документации он просто «утонет» в многочисленных описаниях итерационных изменений, выполненных в различных местах системы.

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

Нажми на кнопку — получишь непонятный результат

«Клавиша имитации ручки выполняет переключение из исходного меню в меню ручек управления, которое позволяет выполнить функции ручек управления с помощью клавиши».bash.im

Давайте ещё немного поговорим об интерфейсах. Техническим писателям часто приходится описывать поля в окнах приложений. Обычно это списки из пар «Название поля — описание». Если нам нечего добавить к названию поля, мы понимаем, что интерфейс спроектирован хорошо, а логика работы системы проста и понятна. Это характерный показатель того, что название поля полностью описывает его назначение и никаких исключений и особенностей в его работе нет.

Но, к сожалению, так бывает редко. Чаще нам встречаются объекты с непонятным названием и назначением. Сколько раз мне приходилось описывать поля с названием «Дата начала» или просто «Дата»!

Вот признаки плохого интерфейса, которые сразу видны техническому писателю:

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

Мне приходилось описывать интерфейсы, в которых на одной панели рядом было расположено несколько кнопок с одинаковыми пиктограммами и разным назначением. В таких случаях писатель вынужден конструировать пассажи вроде такого: «Чтобы создать запись, нажмите первую кнопку [+] на панели инструментов таблицы в левом верхнем углу окна».

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

Изъян привёл к конфузу

Решили, что «баг» — это «изъян», а «инцидент» — «конфуз».bash.im

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

Простой пример: один и тот же объект во внутренних документах может называться «системным параметром», «параметром системы», просто «параметром» или даже «записью в таблице параметров». Для разработчиков системы может быть понятно, что всё это — один и тот же объект. Для пользователя же это совсем не так очевидно. Может быть, после некоторого размышления, он догадается, что все эти названия описывают одно и то же. Но мы же любим наших пользователей, зачем постоянно заставлять их решать подобные головоломки?

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

• «Функция … доступна в следующих режимах …»
• «Чтобы …, выполните в приложении … следующие действия: …»
• «Задайте системный параметр …»

Для фигур описания иногда составляют отдельные словари или справочники. Казалось бы, мелочь. Но пользователь привыкает к определённым конструкциям и фразам. Если в одном месте документа написано «Выберите режим», а в другом «Перейдите в режим», у пользователя может возникнуть сомнения: здесь описано одно и то же действие или разные?

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

Вратарь разработки

Технический писатель — лучший гуманитарий среди технарей и лучший технарь среди гуманитариев.Михаил Острогорский

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

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

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

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

Во всём мире профессия technical writer (или technical author) считается престижной и перспективной. Спрос на технических писателей обычно превышает предложение. Многие переходят в технические писатели из других профессий — переводчиков, аналитиков, даже программистов. У нас интереснее!

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