В прошлой статье я обещала, что расскажу, как сделать документы легче для восприятия. Есть два основных направления: текстовка и структура документа. Сегодня поработаем с текстами. Технические документы на русском читаются особенно тяжело, и добиться легкости в них сложнее, чем в английском. Как можно исправить многословные, громоздкие документы? Давайте попробуем сделать их конкретнее, проще, короче, и последовательнее.
Конкретнее
Документы должны быть написаны для конкретной целевой аудитории с конкретной целью. Так, чтобы предполагаемый пользователь прочитал, понял, и сделал по инструкции то, что хотел.
Целевая аудитория кажется каким-то внешним фактором, не влияющим на документы, но это не так. Очень много проблем в доках решается именно отсылкой к ЦА. Например, насколько понятен этот текст? За всех мы сказать не можем: мне, например, понятен, а вот ему не очень. Так мы далеко не уедем, нужно какое-то решение. А именно: понятно ли это для целевой аудитории? Рассмотрим пример.
Я писала документы для Acronis Cyber Infrastructure, это когда из серверов делают кластер, а его используют для storage и virtual machines. Упрощенно, этот продукт рассчитан на enterprises, в частности, на сервис-провайдеров. ЦА документов — системные администраторы, и не самые простые. Обычному пользователю они будут непонятны. Но это не bug, это by design. Если бы мы писали эти доки для обычных пользователей, то:
- Нужно было бы объяснять все концепты storage и HCI очень подробно и понятно. Такой dummy guide, для чайников.
- Нельзя было бы использовать общепринятые термины сферы, нужно было бы упрощать и описывать. Например, вместо «node», возможно, был бы «server», потому что это слово более употребимо и понятнее всем, хотя оно не передает роли сервера в кластере.
Короче говоря, это были бы совсем другие документы.
Плохо, когда для доков не определена ЦА. Начинаются метания: а это достаточно понятно? А это не слишком элементарно? К вопросу о ГОСТах и ЕСПД. Там как раз часто целевая аудитория — люди, которые почти не умеют пользоваться компьютером. Сейчас таких мало. Поэтому документ на обычного современного юзера, написанный по ЕСПД, может получиться очень тяжелым, перегруженным ненужными деталями. Зато, вероятно, в момент написания ГОСТов он четко попадал бы в ЦА.
Заметки на полях
- В начале документа неплохо иметь раздел Target audience, чтобы было сразу понятно, для кого написан документ. К сожалению, часто там написано: «Для всех, кто читает этот документ или использует наш продукт». Если вам попадется нормальный раздел, где четко описана целевая аудитория, скиньте, пожалуйста, в комменты, с удовольствием почитаю.
- Иногда документ рассчитан на более-менее общую аудиторию, но есть пара сложных моментов для знатоков, например, какие-то хитрые настройки. Такие вещи можно убирать в knowledge base.
- Даже если вы пишете доку для админов и сразу это обозначаете в разделе Target audience, все равно придут люди, которые вообще не шарят. И они станут писать вам: «А что это? А это? А почему так сложно?» Будьте готовы.
Проще
Традиция русских конструкторских текстов — очень подробно объяснять то, что и так уже давно знакомо и понятно обычному пользователю. Я рекомендую убирать избыточные термины и объяснения, такие как «исполняемый файл» в первом примере или «флаг для создания ярлыка на рабочем столе может быть использован для запуска ПО на выполнение» во втором.
Было
Для установки программы необходимо запустить исполняемый файл «wizard.exe» и следовать указаниям мастера установки.
Стало
Чтобы запустить мастер установки, дважды нажмите на файл «wizard.exe».
Было
В этом окне можно установить флаг для создания значка (ярлыка) на рабочем столе, который может быть использован для запуска ПО на выполнение. После задания значения флага следует нажать кнопку «Далее».
Стало
При необходимости, установите флажок «Создать значок на рабочем столе». Нажмите «Далее».
Заметки на полях
- Совершенно спокойно можно убирать из доков описание общих свойств элементов GUI. То есть если вы описываете таблицу, а в ней (ничего себе!) можно поменять ширину столбцов перетаскиванием границы, это писать необязательно. Реальный пример: Размеры частей окна и ширина колонок могут быть изменены путем перемещения разделительных полос левой кнопкой мыши. Положение окна можно изменить перемещением строки заголовка с помощью левой кнопки мыши (ЛКМ).
- Иногда исходный текст настолько запутанный, что даже не знаешь, с какой стороны подступиться. Самое сложное здесь — понять, что же имеется в виду, а уже с пониманием будет легче подобрать простые слова. Обычно такие тексты просто нужно переписать начисто. Вот, поломайте голову над таким примером: Пользователь имеет возможность изменить положение объекта вручную, перетащив его с помощью ЛКМ в удобное положение. Существует два способа изменения положения объекта. 1-ый способ заключается в свободном перемещении, когда можно выбрать любую позицию для установки объекта. 2-й способ, когда позиция имеет фиксированное место с дискретным углом 45? и фиксированным удалением от точки пересечения графика с визиром.
Короче
Недавно на одном из вебинаров услышала очень точную фразу: «Каждое слово, которое вы пишете, пользователь читать не хочет». Согласна на 100%. Но при этом, признаюсь, мне знакомо чувство, когда хочется еще дописать, и еще немного объяснить, и повторить то же другими словами, ну, чтобы точно дошло! Борюсь с этим чувством, и вам советую.
Сделать текст короче — это не совсем то же самое, что сделать его проще. Когда мы упрощаем текст, мы убираем лишние технические детали. А когда мы сокращаем его, мы убираем фигуры речи и лишние обычные слова. Например, если пункт 2 идет после пункта 1, не нужно писать «После выполнения пункта 1». Или вместо «следует нажать» лучше писать «нажмите».
Было
После выполнения указанных действий в режиме «Р» для печати билета с одним из запрограммированных тарифов от 1 до 9 достаточно нажать соответствующую цифровую клавишу. Билет будет автоматически отпечатан.
Стало
Чтобы напечатать билет с запрограммированным тарифом от 1 до 9, нажмите на соответствующую цифру.
Часто в русских инструкциях попадаются длинные абзацы сплошного текста, которые нужно разбить на несколько абзацев и сократить. Посмотрим на большой абзац, в котором спрятана инструкция. Процедура на несколько шагов сплошным текстом, еще и с нарушением логического порядка — это боль. Но все поправимо. Разбиваем на шаги, упорядочиваем по логике — и вуаля!
Было
Для обновления, нужно временно скопировать файл «Ф» на компьютер с ПО, обновить программой «П» (указать путь к файлу «Ф»), затем скопировать файл обратно на сетевой ресурс. Перед началом обновления, необходимо убедиться в достаточном количестве свободного места на диске, где расположен файл «Ф», – это необходимо для создания резервной копии. Объём свободного места должен быть не менее размера обновляемого файла. Если свободного места недостаточно, программа выведет соответствующее сообщение.
Стало
Обновление
- Убедитесь, что на диске, где расположен файл «Ф», достаточно места для создания резервной копии.
- Скопируйте файл «Ф» из сетевого хранилища на компьютер с программой «П»
- В программе «П» укажите путь к файлу «Ф» и обновите его.
- Скопируйте обновленный файл «Ф» обратно в сетевое хранилище.
Заметки на полях
- Когда мы работаем с большими абзацами сплошного текста, нужно помнить про visual effectiveness. Слишком много букв подряд — и читать уже сложно. Иногда достаточно разбить на шаги или абзацы, а иногда можно подумать про схему. Толковая схема решает. Но чтобы сделать толковую схему, нужно понимать суть процедуры от и до. Здесь может пригодиться помощь разработчика или program manager.
Последовательнее
Технический писатель — человек творческий, поэтому названий для одной и той же операции может быть много: «нажать», «щелкнуть», «кликнуть», и все в одном документе. И помножим это на количество творческих людей, работающих над одним документом. Я за консистентность. Одна и та же операция должна называться одинаково. Если вам нравится «Щелкнуть», то так и пишите везде. Если «Нажать» – аналогично. Выберите подходящий термин и последовательно применяйте его везде. А еще лучше, заведите корпоративный глоссарий, хотя бы на русском, и там пропишите нужные фразы. +500 к консистентности, и еще помогает новичкам быстрее освоиться.
Заметки на полях
- Иногда непонятно правильное название чего-то на русском, но известно его английское название. Например, у нас есть «нода», от английского «node». Как найти верное русское слово? Можно зайти на глоссарий Microsoft. Там выбираем английский исходный язык и русский язык перевода, вводим слово на английском, и смотрим предложенные варианты на русском. Получаем «узел».
- Если уж решились сделать документы последовательнее, эти правки должны быть применены повсеместно. Иначе какой смысл? Обычно такие изменения затрагивают больше всего текстов. Поэтому здесь нужно правильно рассчитать сроки и затраты. И особенно важно не забыть про локализацию, ведь для них это означает очень масштабное изменение в нескольких языках сразу.
- Когда в документах то disk, то drive, это не очень хорошо. Но когда то же самое в GUI, это совсем плохо. Поэтому на GUI смотрим особенно внимательно и запоминаем все варианты, которые потом нужно будет править.
Ресурсы
Прежде чем браться за исправление документов, можно почитать разные книги, чтобы лучше понимать, что к чему.
- «Слово живое и мертвое» Норы Галь. Классика.
- «Живой как жизнь» Корнея Чуковского, глава «Канцелярит». Классика.
- «Пиши, сокращай» Максима Ильяхова. Свежий взгляд на старые проблемы + очень практичный подход. Здесь подробно описано, как именно можно сократить тексты.
- Developing Quality Technical Information: A Handbook for Writers and Editors от Gretchen Hargis и др. Здесь много про цели, задачи, ЦА документов. А еще хорошие примеры и практичные советы.
P.S. Отдельная тема – почему английский такой краткий, четкий, и понятный по сравнению с русским. Хотя, например, испанский тоже так себе в легкости, не лучше нашего. Но это уже языковедение. Пока ходить туда не будем, если нужно, напишите в комментах.
smart_alex
Потому, что английский — это упрощённый (обеднённый в описании образов окружающего мира) вариант русского.
Зато английский, да, лучше подходит для описания формально-логических задач.
Marivolina Автор
интересный вариант, но не могу согласиться с тем, что английский — это вариант русского. а по поводу «английский лучше подходит для описания формально-логических задач», это да, но вот почему? =)
smart_alex
Здесь всё очень просто: то, что написано на английском, всегда можно адекватно перевести на русский, но многие вещи невозможно адекватно с русского перевести на английский. Почему? Именно потому, что русский более полно описывает окружающий нас мир.
Классический пример: Пушкина много раз пытались перевести на английский, но безуспешно. Набоков после многочисленных попыток констатировал: «Золотая клетка осталась, а птичка улетела».
«Птичка» — это и есть богатство описания явлений внешнего и внутреннего мира. В этом смысле все нативно англо-говорящие люди живут в искусственно ограниченном «пузыре восприятия». Для них просто не существует тех оттенков восприятия, которые есть у нас.
Marivolina Автор
я слышала про такое, но это ошибочное мнение, что один язык может быть однозначно беднее или богаче другого. языки разные. в некоторых отношениях, лексических средств аглийского меньше, в некоторых — больше. например, в английском языке очень богатые описания моря, или тумана, а в русском их намного меньше. хотя есть, конечно, темы, которые шире раскрыты в русском.
smart_alex
Я бы вам ещё порекомендовал поискать и познакомиться с исследованиями о словарном составе русского и английского языков и словарном запасе их носителей.
Мне встречались исследования, где утверждалось, что словарный состав английского языка на порядок меньше русского (чисто формально), а словарный запас Шекспира по количеству слов соответствует словарному запасу среднестатистического русскоговорящего люмпена.
Marivolina Автор
можно, пожалуйста, ссылку на эти исследования? чтобы уже детально обсудить) интересны методы и принципы подсчета.
smart_alex
К сожалению, я не предполагал, что мне понадобится предоставлять ссылки, поэтому их не конспектировал. Но при наличии интернета, я думаю, можно найти много интересных материалов на эту тему.
astec
Зато некоторые слова могут нести гораздо больше смыслов и оттенков и гораздо чаще могут менять своё значение в зависимости от контекста или порядка. Самый простой пример PHRASAL VERB. "You have to get out" и "You, get out!", "Pls get it out" — слова одни, смысл совершенно разный. Невозможно просто тупо посчитать по количеству слов.
Некоторый вещи красивее в русском, некоторые в английском. Я бы сказал 50/50.
Надо прожить языком достаточно долго только чтобы начать замечать такие моменты.
astec
Я вот живу в англоговорящей стране и могу с уверенностью заявить что в английском огромное количество моментов которые сложно перевести на русский.
Мне гораздо чаще сложнее сделать перевод на русский чем наоборот.
Последний случай пытался объяснить смысловую нагрузку "glorious cakery". Смысл передать можно, но одним-двумя словами мне кажется нереально.
Конечно и наоборот в русском есть замечательные слова и выражения который сложно перевести литературно.
Огромное значение имеет культурный контекст — он в разных языках и странах разный.
Не стоит упрощать. Я люблю английский язык — он по своему очень богат и прекрасен.
Marivolina Автор
согласна. а еще, иногда выражения на разных языках у меня вызывают разный отклик в душе, и они отражают разные эмоции. поэтому вроде говоришь по-русски, но как-то не находишь аналога в своем языке, и говоришь какие-то междометия, или короткие ситуативные фразы на английском. потому что они вот в этой ситауции лучше отражают. например: Oh my Gosh! Oh no. Yay! а я еще в свое время изучала (и даже преподавала) фонетику английского, поэтому еще и интонация другая, нерусская, и звучит забавно) а когда по-английски говорю, часто не могу найти аналога русского мата, и тоже его вставляю прямо в английскую речь)
qark
При этом Набоков считал, что не справился с переводом "Лолиты" на русский.
Mikilangelo
Английский очень хорошо структурирован. Вот особенно для логических задач, где используются подобные формы Субъект -> предикат -> объект, там превосходство английского оно просто колоссальное.
К примеру, я составлял граф знаний из фактов и утверждений при обработке текстов.
На английском одна форма почти всегда. И здесь очень легко понять где предикат, где субъект и где объект. Вот есть простой факт утверждение, что что-то является чем-то
Возьмем настоящее простое время.
На английском это просто
X is Y
Субъект X является Y
На русском потяжелее гораздо. Очень много вариаций может оказаться в тексте.
X это Y
X является Y
X — Y
X это значит Y
X есть Y
Та же история и с нейросетями. Когда язык лучше структурирован. Сеть на нем обучается лучше.
Marivolina Автор
очень ценный комментарий, спасибо. и добавим к этому еще русское словообразование, когда суффиксы и окончания создают столько новых длинных форм от одного корня, а в английском слово часто меняет часть речи, оставаясь простым и коротким. в итоге объем текста вырастает значительно.