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

Как их только не называют: техписы, техрайтеры, документаторы... Хорошо, хоть не архивариусы!

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

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

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

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

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

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

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

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

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

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

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

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

В-третьих, каждый должен заниматься своим делом. Например, математику или физику часто проще написать формулу, чем объяснить словами какой-то закон. Программисту же проще выражать свои мысли в виде кода и алгоритмических конструкций. Аналитику, пожалуй, важнее писать грамотно и понятно, ведь неточность в задании вполне может привести к ошибке в реализации. Но у аналитика есть свои инструменты — всякие UML и BPMN — графические нотации, которые помогают чётко формализовать все требования и не допускают разночтений в их понимании. То, что непонятно или неясно из текста технического задания, всегда можно уточнить на диаграмме.

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

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

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

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

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

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

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

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

«ИИ имеет сложную структуру, поэтому для упрощения работы с ИИ предоставляется специальная утилита, пока не разработанная»
Из документации к библиотеке

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

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

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

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

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

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

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

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

• объекты с непонятным назначением, с неочевидным названием или вовсе без названия;

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

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

Только наши разработчики могли в программе в окне с вопросом «Не сохранять изменения?» сделать кнопки «Да» и «Нет». Да, не сохранять... Нет, не сохранять...
bash.im

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

Метаданные или метачушь

Ошибка выполнения метода: «Метод выполнился без ошибок».

Здесь под метаданными я понимаю описание различных внутренних объектов системы:

• описание таблиц и полей базы данных;

• описание параметров функций API-интерфейсов;

• всплывающие подсказки к объектам интерфейса;

• информативные и понятные сообщения об ошибках.

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

А у нас в проекте определена константа, в которой хранится количество секунд в минуте. Это всё, что вам нужно знать о нашем проекте.
bash.im

К сожалению, аккуратное и правильное заполнение метаданных — это утопия, об этом писал Кори Доктороу в своей статье «Метачушь». А раз так, технические писатели и дальше будут продолжать писать тысячестраничные справочники по базам данных и API-интерфейсам.

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

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

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

Вот что об этом пишет в книге «Разработка документации пользователя программного продукта» Юрий Кагарлицкий: «Строго говоря, упорядоченное употребление терминологии сотрудниками чрезвычайно важно для эффективной деятельности любого предприятия или организации. Это относится не только к документации пользователя, а к любым видам письменной и устной коммуникации, встречающимся в корпоративной практике». И далее: «В современных крупных компаниях всё чаще создаются особые терминологические службы — для управления терминологией (terminology management) в масштабе всей компании».

Скажите, в вашей компании есть терминологическая служба?

— Придумай мне более короткое название для состояния разработки «Поставлена задача проектировщикам».
— Проектировщики озадачены.
bash.im

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

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

• «Функция … доступна в следующих режимах ...»

• «Чтобы …, выполните в приложении … следующие действия: ...»

• «Задайте системный параметр ...».

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

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

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

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

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

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

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

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

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

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

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