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

Конкретнее

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

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

Я писала документы для Acronis Cyber Infrastructure, это когда из серверов делают кластер, а его используют для storage и virtual machines. Упрощенно, этот продукт рассчитан на enterprises, в частности, на сервис-провайдеров. ЦА документов системные администраторы, и не самые простые. Обыкновенному человеку они будут непонятны. Но это не bug, это by design. Если бы мы писали эти доки для обычных пользователей, то:

1. Нужно было бы объяснять все концепты storage и HCI очень подробно и понятно. Такой dummy guide, для чайников.
2. Нельзя было бы использовать общепринятые термины сферы, нужно было бы упрощать и описывать. Например, вместо node, возможно, был бы server, потому что это слово более употребимо и понятнее всем, хотя оно не передает роли сервера в кластере.

Короче говоря, это были бы совсем другие документы.

Плохо, когда для доков не определена ЦА. Начинаются метания: а это достаточно понятно? А это не слишком элементарно? К вопросу о ГОСТах и ЕСПД. Там как раз часто целевая аудитория люди, которые почти не умеют пользоваться компьютером. Сейчас таких мало. Поэтому документ на обычного современного юзера, написанный по ЕСПД, может получиться очень тяжелым, перегруженным ненужными деталями. Зато, вероятно, в момент написания ГОСТов он четко попадал бы в ЦА.

Заметки на полях

• В начале документа неплохо иметь раздел Target audience, чтобы было сразу понятно, для кого написан документ. К сожалению, часто там написано: Для всех, кто читает этот документ или использует наш продукт. Если вам попадется нормальный раздел, где четко описана целевая аудитория, скиньте, пожалуйста, в комменты, с удовольствием почитаю.
• Иногда документ рассчитан на более-менее общую аудиторию, но есть пара сложных моментов для знатоков, например, какие-то хитрые настройки. Такие вещи можно убирать в knowledge base.
• Даже если вы пишите доку для админов и сразу это обозначаете в разделе Target audience, все равно придут люди, которые вообще не шарят. И они станут писать вам: А что это? А это? А почему так сложно? Будьте готовы.

Проще

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

Было

Для установки программы необходимо запустить исполняемый файл wizard.exe и следовать указаниям мастера установки.

Стало

Чтобы запустить мастер установки, дважды нажмите на файл wizard.exe.

Было

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

Стало

При необходимости, установите флажок Создать значок на рабочем столе. Нажмите Далее.

Заметки на полях

• Совершенно спокойно можно убирать из доков описание общих свойств элементов GUI. То есть если вы описываете таблицу, а в ней (ничего себе!) можно поменять ширину столбцов перетаскиванием границы, это писать необязательно. Реальный пример: Размеры частей окна и ширина колонок могут быть изменены путем перемещения разделительных полос левой кнопкой мыши. Положение окна можно изменить перемещением строки заголовка с помощью левой кнопки мыши (ЛКМ).
• Иногда исходный текст настолько запутанный, что даже не знаешь, с какой стороны подступиться. Самое сложное здесь понять, что же имеется в виду, а уже с пониманием будет легче подобрать простые слова. Обычно такие тексты просто нужно переписать начисто. Вот, поломайте голову над таким примером: Пользователь имеет возможность изменить положение объекта вручную, перетащив его с помощью ЛКМ в удобное положение. Существует два способа изменения положения объекта. 1-ый способ заключается в свободном перемещении, когда можно выбрать любую позицию для установки объекта. 2-й способ, когда позиция имеет фиксированное место с дискретным углом 45 и фиксированным удалением от точки пересечения графика с визиром.

Короче

Недавно на одном из вебинаров услышала очень точную фразу: Каждое слово, которое вы пишите, пользователь читать не хочет. Согласна на 100%. Но при этом, признаюсь, мне знакомо чувство, когда хочется еще дописать, и еще немного объяснить, и повторить то же другими словами, ну, чтобы точно дошло! Борюсь с этим чувством, и вам советую.

Сделать текст короче это не совсем то же самое, что сделать его проще. Когда мы упрощаем текст, мы убираем лишние технические детали. А когда мы сокращаем его, мы убираем фигуры речи и лишние обычные слова. Например, если пункт 2 идет после пункта 1, не нужно писать После выполнения пункта 1. Или вместо следует нажать лучше писать нажмите.

Было

После выполнения указанных действий в режиме Р для печати билета с одним из запрограммированных тарифов от 1 до 9 достаточно нажать соответствующую цифровую клавишу. Билет будет автоматически отпечатан.

Стало

Чтобы напечатать билет с запрограммированным тарифом от 1 до 9, нажмите на соответствующую цифру.

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

Было

Для обновления, нужно временно скопировать файл Ф на компьютер с ПО, обновить программой П (указать путь к файлу Ф), затем скопировать файл обратно на сетевой ресурс. Перед началом обновления, необходимо убедиться в достаточном количестве свободного места на диске, где расположен файл Ф, это необходимо для создания резервной копии. Объём свободного места должен быть не менее размера обновляемого файла. Если свободного места недостаточно, программа выведет соответствующее сообщение.

Стало

Обновление

1. Убедитесь, что на диске, где расположен файл Ф, достаточно места для создания резервной копии.
2. Скопируйте файл Ф из сетевого хранилища на компьютер с программой П
3. В программе П укажите путь к файлу Ф и обновите его.
4. Скопируйте обновленный файл Ф обратно в сетевое хранилище.

Заметки на полях

• Когда мы работаем с большими абзацами сплошного текста, нужно помнить про visual effectiveness. Слишком много букв подряд и читать уже сложно. Иногда достаточно разбить на шаги или абзацы, а иногда можно подумать про схему. Толковая схема решает. Но чтобы сделать толковую схему, нужно понимать суть процедуры от и до. Здесь может пригодиться помощь разработчика или program manager.

Последовательнее

Технический писатель человек творческий, поэтому названий для одной и той же операции может быть много: нажать, щелкнуть, кликнуть, и все в одном документе. И помножим это на количество творческих людей, работающих над одним документом. Я за консистентность. Одна и та же операция должна называться одинаково. Если вам нравится Щелкнуть, то так и пишите везде. Если Нажать аналогично. Выберите подходящий термин и последовательно применяйте его везде. А еще лучше, заведите корпоративный глоссарий, хотя бы на русском, и там пропишите нужные фразы. +500 к консистентности, и еще помогает новичкам быстрее освоиться.

Заметки на полях

• Иногда непонятно правильное название чего-то на русском, но известно его английское название. Например, у нас есть нода, от английского node. Как найти верное русское слово? Можно зайти на глоссарий Microsoft. Там выбираем английский исходный язык и русский язык перевода, вводим слово на английском, и смотрим предложенные варианты на русском. Получаем узел.
• Если уж решились сделать документы последовательнее, эти правки должны быть применены повсеместно. Иначе какой смысл? Обычно такие изменения затрагивают больше всего текстов. Поэтому здесь нужно правильно рассчитать сроки и затраты. И особенно важно не забыть про локализацию, ведь для них это означает очень масштабное изменение в нескольких языках сразу.
• Когда в документах то disk, то drive, это не очень хорошо. Но когда то же самое в GUI, это совсем плохо. Поэтому на GUI смотрим особенно внимательно и запоминаем все варианты, которые потом нужно будет править.

Ресурсы

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

• Слово живое и мертвое Норы Галь. Классика.
• Живой как жизнь Корнея Чуковского, глава Канцелярит. Классика.
• Пиши, сокращай Максима Ильяхова. Свежий взгляд на старые проблемы +очень практичный подход. Здесь подробно описано, как именно можно сократить тексты.
• Developing Quality Technical Information: A Handbook for Writers and Editors от Gretchen Hargis и др. Здесь много про цели, задачи, ЦА документов. А еще хорошие примеры и практичные советы.