Михаил Острогорский требует от технических текстов понятности, однозначности и четкой структуры

Придумать жанр

Когда я только начинал заниматься технической документацией в середине 1990-х годов, никто не знал, как надо, и в то же время все по-своему что-то знали. 

С одной стороны, была документация, которая нам досталась от советских времен. Но она уже тогда воспринималась как нечто устаревшее и даже немного комичное. У меня, например, была вычислительная машина ЕС-1841, которую поставляли вместе с такой документацией. С ней в комплекте шло устройство, отдаленно напоминавшее современную мышь (уже тогда продавались более удобные мыши западного производства). Внутри вместо привычного резинового шарика был полностью металлический, похожий на шарик из подшипника.

Шнур у этой мыши был толщиной с палец и практически не гнулся. В документации устройство гордо именовалось «манипулятор “Колобок”».

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

С другой стороны, была англоязычная документация на западные программные продукты — то же руководство Inside Macintosh для Mac OS. Она служила ориентиром, но не всегда подходила к нашим реалиям. Возникла потребность в русскоязычной пользовательской документации для коммерческих продуктов. Нужно было придумать этот жанр, предложить язык и стиль таких текстов.

Дать имена объектам и действиям

Сразу возникло множество вопросов. Как мы будем излагать материал, как будем его структурировать? Какие термины мы будем использовать — например, для элементов интерфейса? 

Допустим, есть элементы check box и radio button. Первый позволяет управлять параметром с состояниями «включено» и «отключено»; он выглядит как квадратик, где можно поставить галочку или убрать ее. Второй — переключатель для выбора одной опции из набора. Название родилось из аналогии с кнопками, которые использовались в автомобильных радиоприемниках для выбора предварительно настроенной радиостанции.

Нужно было не только придумать термины, но и предложить соответствующие фигуры описания. Хорошо, переключатель. А что мы предлагаем пользователю с ним сделать?

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

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

Позаботиться о понятности

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

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

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

И это первая важная черта, которая делает технический текст понятным аудитории: он должен быть выстроен от заведомо известного (или введенного нами ранее) к новому. Очень важно уметь предугадывать те вопросы, которые могут возникнуть у читателя, и на эти вопросы ему отвечать. Это необходимо, но этого недостаточно.

Что мешает специалистам писать понятные текстыВ книге «Чувство стиля» психолингвист Стивен Пинкер предлагает решения, основанные на данных когнитивной психологииВторой момент — читателю должно быть понятно, как наш документ устроен в целом. Технический текст, особенно большого объема, редко читают от начала до конца. Его читают по мере необходимости — значит, должна быть возможность быстро найти нужную страницу. А если там что-то непонятно, то быстро найти в документе тот материал, на который прочитанное опирается. Текст должен быть четко структурирован — и на уровне документа в целом, и на уровне сплошного текста внутри отдельных частей.

Подстроиться под заказчика и аудиторию

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

Например, мы разрабатывали руководство пользователя к довольно крупной и сложной геоинформационной системе. Нужно было объяснить не самые простые концепции, так что получился документ на несколько сотен страниц. Мы его отдали заказчику. Звонит немолодой инженер, который принимал работу: «Приезжайте немедленно».

Мы приехали. «Документация никуда не годится». А что же с ней не так? «Так документацию не пишут». Час от часу не легче… Просим объяснить, что конкретно ему не нравится. «В ней устаревшие слова». Пожалуйста, говорим, назовите хотя бы одно. «У вас написано и снова нажмите на кнопку ОК. А так в документации писать нельзя, надо писать и повторно нажмите на кнопку ОК».

Оказалось, в тексте было несколько слов, которые его раздражали. Мы их заменили, и документация перестала «никуда не годиться». Таких курьезов, самых разных, было довольно много.

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

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

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

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

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

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

Переизобрести способ описания для систем с ИИ

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

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

— Какую задачу вы сейчас решаете?

— Вот эту.

— Как вы это делаете?

— Сначала иду сюда, потом сюда, потом открывается такое-то окно, я в нем заполняю такие-то поля.

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

Мы всегда можем утверждать, что когда система находится в определенном состоянии, то из этого состояния пользователь может пойти туда-то и туда-то, чтобы в итоге получить прогнозируемый результат. Если программа тщательно спроектирована, отлажена, протестирована, она никогда не сделает ничего такого, что разработчик или пользователь туда не закладывали. Чтобы они сказали: «Ну ничего себе, мы такого не ждали!» 

Система с искусственным интеллектом устроена так, что каждый твой шаг меняет ее состояние. Ты что-то сделал — она чему-то научилась.

Это немного другая система теперь. Как про это писать? Как ее изучать? Пока это не вполне понятно.

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

Решить главную задачу

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

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

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

Допустим, в руководстве попадается фраза «данные сохраняются в базе». Читателю надо как-то понять, что значит «сохраняются». Кем сохраняются — системой или самим пользователем? Ему тут указывают на порядок его действий — или ему объясняют, что нечего беспокоиться, всё само сохранится? Если он ошибется (а на самом деле если ошибся автор руководства), могут быть потеряны важные данные.

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