Блог технического писателя Ильи Жукова

Как повысить качество текста инструкций

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

Качество текста

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

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

  • Требования к качеству содержания (оглавления).
  • Требования к качеству текста в разделах инструкции.

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

 

Порядок работы над текстом

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

 

Проверка структуры документа

проработка структуры  

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

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

Параллельные конструкции. Здесь все понятно: «Создание документа», «Редактирование документа», а «Как удалить документ» меняем на «Удаление документа». Или наоборот: всё через «Как…», например, если это ответы на часто задаваемые вопросы.

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

Длина заголовков. Одновременно корректируем длину заголовков. Оптимальная длина — не более 6 знаменательных слов (вспоминаем про закон Миллера). В конце заголовка точки быть не должно. Но если вы пишете по ГОСТ, пропустите эту рекомендацию. Согласно ГОСТ 2.105-95 заголовок может состоять из нескольких предложений, разделенных точкой (без точки в конце).

Глубина структуры. Хорошо, если глубина содержания в документе ровная и составляет 3-4 уровня вложенности. Ничего страшного, если в одних разделах первого уровня есть только подразделы, а в других — пункты и подпункты (в терминах ГОСТ). Но иногда бывает, что в некоторых разделах глубина превышает 5-6 уровней вложенности. В этом случае лучше переработать текст и поднять значимую информацию наверх.

Проверка ключевых слов. Первым делом находим разделы без ключевых слов и добавляем ключевые слова. Затем собираем документ и изучаем получившийся Указатель. Ищем одни и те же ключевые слова в разных падежах и числах, например: ссылка, ссылкой, ссылки и т.п. Исправляем, например, на именительный падеж, единственное число. В результате получаем одно ключевое слово в Указателе, которое ведет на разные разделы.

 

Проверка текста

проработка текста  

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

  • В тексте не должно быть ошибок и опечаток.
  • Текст должен быть кратким и ясным.
  • Похожие формулировки должны быть единообразными.
  • Названия элементов интерфейса должны быть точными.

Ошибки и опечатки. Выгружаем текст в текстовый редактор и проверяем его спелл-чекером. В результате исправляем основную массу ошибок и опечаток, но не все. Чем пользуюсь? Word 2010 или ОРФО.

Краткость и ясность. Дальше решаем вопрос с замыливаением: меняем тип и размер шрифта. Если использовался шрифт с засечками (например, Times New Roman), меняем его на шрифт без засечек (например, Arial). Читаем текст вслух. Все места, на которых споткнулись или запнулись, отмечаем и прорабатываем.

Обращаем особое внимание на большие абзацы и длинные сложные предложения. Делим их на части и упрощаем. Также проверяем абзацы, состоящие из одного предложения. В норме так не должно быть, но бывают исключения. По возможности меняем пассивный залог на активный. Где уместно, добавляем подзаголовки (например, как здесь в строке абзаца). Параллельно исправляем пропущенные ошибки и опечатки. Переработанный текст читаем еще раз. Хороший текст должен читаться свободно без запинок.

Формулировки. В тексте инструкций рекомендуется использовать стандартные формулировки в перекрестных ссылках, ссылках на рисунки, таблицы и т.п. Проверяем единообразие формулировок: «Подробное описание … смотрите в …», (см. рис. 1) и другие. Список таких формулировок лучше составить в начале пути. Сэкономит время во время проверки!

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

 

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

 

Выводы

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

 

Добавить комментарий

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

Перевод выходных документов в Help and M…

Выбрав русский язык и русскую кодировку в настройках проекта Help and Manual, многие авторы после первой сборки удивляются, увидев в выходных документах английские сло...

Читать полностью...

Размер и расположение окна CHM при перво…

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

Читать полностью...

Рваные края скриншотов в Help and Manual

Многие платные редакторы скриншотов, например, SnagIt, FastStone Capture и др., умеют создавать эффект рваных краев. В сети Интернет можно найти множество видеоуроков ...

Читать полностью...
новое в Help and Manual 9

Новое в Help and Manual 9

23 ноября 2022 года компания EC Software к 25-летнему юбилею выпустила 9-ю версию программного комплекса Help and Manual (выходит c 1997 года). Комплект шаблонов Premi...

Читать полностью...

Создание CHM-справки в бесплатной програ…

KEL CHM Creator — это «новая» хорошо забытая программа, выпущенная в 2012 году, предназначенная для создания и декомпиляции CHM-файлов. Программа не требовательна к ре...

Читать полностью...

KEL CHM Creator — бесплатная программа д…

Если вам нужно создать CHM-файл, и вы больше не хотите пользоваться глючной программой HTML Help Workshop, тогда KEL CHM Creator — это ваш вариант. Программа позволяет...

Читать полностью...
ключевые слова

Ключевые слова в Help+Manual

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

Читать полностью...

HTML Help Workshop – бесплатная программ…

В 1997 году Microsoft выпустила новый формат справки, HTML Help (CHM), а также бесплатную программу для создания и редактирования справки в этом формате — HTML Help Wo...

Читать полностью...

HelpNDoc — бесплатная альтернатива Help+…

Еще одной альтернативой RoboHelp и Help&Manual является программа HelpNDoc от французского разработчика, компании IBE Software. Это практически полный аналог HelpS...

Читать полностью...

HelpSmith — достойная альтернатива Help+…

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

Читать полностью...
отечественная программа для разработки справки

Dr.Explain — отечественная программа для…

За почти 30-летнюю историю существования RoboHelp и Help&Manual стали стандартом средств разработки справки и пользовательской документации в среде Windows. Сегодн...

Читать полностью...
вычитка текста

Как вычитать свой текст: инструкция для …

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

Читать полностью...

Закон построения нехудожественного текст…

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

Читать полностью...

Примечания и предупреждения в тексте инс…

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

Читать полностью...

Методика чтения научных книг

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

Читать полностью...

Книга «Пиши, сокращай: как создавать сил…

Наводя порядок в книжном шкафу, нашел книгу Максима Ильяхова и Людмилы Сарычевой «Пиши, сокращай: как создавать сильный текст». Я прочитал ее летом 2018 года, но отзыв...

Читать полностью...

Все о справке и документации для пользователей!

Следить за новыми статьями:

© Илья Жуков, 2019-2023. Охраняется законом об авторском праве.