До сих пор (Главы 1-4) мы почти все время двигались только в одном направлении и смотрели, фигурально выражаясь, почти исключительно вперед - как написать хорошую документацию. Однако на практике приходится постоянно оглядываться на уже сделанное, подвергать свою работу оценке, опознавать ошибки и исправлять их. Как говорится в рекламе жевательной резинки - пока кто-нибудь не купил Вам это!

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

Мы выделяем ошибки и недочеты следующих видов:

• Фактические
• Логико-стилистические
• Стилистические

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

В настоящем Руководстве эти вопросы не рассматриваются.

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

Общее понятие вместо конкретного.

Комментарий

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

Как исправить

Подобрать и заменить термин

Конкретное понятие вместо общего

Комментарий

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

Примеры

Введите регистрационный номер купленной [следовало бы: приобретенной] Вами копии системы

Как исправить

Подобрать и заменить термин

Двусмысленный предикат

Комментарий

Иногда из текста непонятно, что обозначает предикат - набор свойств данного конкретного субъекта (характеристика) или описание общего набора свойств целого класса субъектов (определение)

Примеры

Microsoft Word - это программный продукт, предназначенный для редактирования текстов и обладающий высокоразвитым пользовательским интерфейсом

Как исправить

Заменить способ выражения предиката, например:

Программный продукт Microsoft Word предназначен для редактирования текстов и обладает высокоразвитым пользовательским интерфейсом.

Смешение целого и части

Комментарий

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

Примеры

Управлять антивирусным пакетом Antiviral Toolkit Pro, установленным на добавленных в логическую сеть AVP рабочих станциях [следовало бы: компонентами антивирусного пакета Antiviral Toolkit Pro, установленных на добавленных в логическую сеть AVP рабочих станциях].

Как исправить

Заменить выражение

Смешение уровней описания продукта; в частности - объекта и его отображения; действий пользователя и действий программы

Комментарий

См. Главу 2 и п. 4.2.1

Примеры

Атрибуты антивирусной защиты получателя сервера находятся [следовало бы: отображаются] на закладке "AVP Settings".

Вы можете загружать антивирусные базы из любого каталога, прописав путь к ним в этом поле [следовало бы: Чтобы антивирусные базы могли загружаться программой из любого каталога, пропишите путь к ним в этом поле]

Как исправить

Провести тщательное разграничение лексики по уровням описания продукта

Неполное описание

Наименование ошибки

Пропущенная валентность

Комментарий

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

Примеры

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

Как исправить

Заполнить валентность

Недостаточно конкретное изложение

Комментарий

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

Примеры

Убедитесь, что на выбранном диске достаточно свободного пространства [следовало бы, как минимум, уточнить, сколько необходимо иметь свободного пространства на диске]

Как исправить

Заменить описание на более конкретное

Однополюсное утверждение

Комментарий

Иногда в документации встречаются утверждения, представляющие собой как бы "половинки" от чего-то большего: логическое ударение падает на определенное понятие, но непонятно, ради чего сделано утверждение, а именно - чему оно противопоставляется. Эту логико-стилистическую погрешность легко идентифицировать: попробуйте после слова или словосочетания, на которые падает логическое ударение, подставить ", а не..."

Примеры

Воспользовавшись специальным картриджем, Вы получаете возможность загружать программу с жесткого диска [следовало бы добавить: а не только с компакт-диска]

Как исправить

Добавить недостающее противопоставление

Попытка выразить в одной фразе несколько мыслей

Комментарий

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

Как исправить

Попробовать разбить предложение на несколько самостоятельных предложений

Нерациональное расположение информации

Комментарий

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

Примеры

Нажмите на кнопку ОК, чтобы отформатировать жесткий диск.

Как исправить

Поменяйте местами тему и рему:

"Чтобы отформатировать жесткий диск, нажмите на кнопку ОК

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

Нестандартное описание, слово или термин

Наименование ошибки

Употребление нестандартного термина

Комментарий

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

Как исправить

Заменить термин на правильный

Употребление нестандартных околотерминологических слов

Комментарий

С каким-либо термином употреблено неправильное околотерминологическое слово

Примеры

Чтобы выполнить процедуру, нажмите на значок [вместо: щелкните мышью по значку]

Как исправить

Замените слово

Употребление нестандартных конструкций для описания процедур

Комментарий

Описание процедуры, для которой существует стандартное клише, выполнено не в соответствии со стандартом.

Как исправить

Употребить правильное клише

Неоднозначно трактуемая синтаксическая связь

Наименование ошибки

Союз ИЛИ

Комментарий

Разделительный союз ИЛИ обладает многозначной семантикой: иногда он соединяет части предложения, иногда же, напротив, разделяет.

Примеры

По всем коммерческим вопросам или [следовало бы: и по] вопросам, связанным с неполной комплектацией системы, обращайтесь в коммерческий отдел

Как исправить

Переработать всю конструкцию так, чтобы связь интерпретировалась однозначно

Союз И

Комментарий

Сочинительный союз И (особенно между глаголами) также очень многозначен. В частности, помимо значения простого перечисления, он может еще иметь оттенки причинно-следственных отношений, а также временного следования. Поэтому конструкции с И часто могут быть истолкованы двусмысленно. Для чистого перечисления иногда лучше подходит союз А ТАКЖЕ, не имеющий других оттенков. Для выражения отношений причины, цели, временного следования предпочтительны другие формы выражения (не союз И)

Примеры

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

В противном случае нажмите на кнопку "Cancel" и прервите процесс установки [следовало бы: В противном случае, чтобы прервать процесс установки, нажмите на кнопку "Cancel"].

Как исправить

Заменить союз И другими союзами

Двусмысленные отглагольные образования

Комментарий

Отглагольные существительные очень удобны для краткого и емкого описания действия самого по себе. Однако они могут порождать двусмысленности - комичные, а иногда и затемняющие содержание. Это связано с тем, что при отглагольных существительных часто отсутствуют (из соображений краткости) слова, поясняющие, кто и над чем совершает действие: Проблемы возникают также и с отглагольными существительными, обладающими значением не действие, а субъекта действия, - такими, как: "получатель", "отправитель" и пр.

Примеры

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

Для лечения [лечения кого? следовало бы: для того чтобы приступить к лечению файлов...] администратору необходимо сначала извлечь файлы из архива, а затем запустить антивирус.

Получатель сервера

Как исправить

Заменить отглагольные существительные на синонимичные глагольные конструкции. Например, конструкции с отглагольными существительными и предлогом ДЛЯ имеет смысл заменять на придаточные с сюзом ЧТОБЫ

Неоднозначно трактуемые зависимости между словами

Комментарий

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

Примеры

Комплект дистрибутивных дискет с AVPDOS 32 в запечатанном конверте

Сообщения, которые приходят в почтовые ящики пользователей, на них самих

Как исправить

Перестроить фразу или добавить уточняющие слова

Переусложненная синтаксическая конструкция

Наименование ошибки

Лишняя служебная часть речи

Комментарий

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

Примеры

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

Как исправить

Убрать лишние служебные части речи

Лишняя "прослойка"

Комментарий

О словах-"прослойках" см.. п. 4.2.1. Иногда вставка "прослойки" делает фразу грамотнее и понятнее. Но очень часто "прослойка" является лишней.

Примеры

Индикатор режима "Caps Lock" [следовало бы: Индикатор "Caps Lock"]

Дождитесь завершения процесса копирования. [следовало бы: Дождитесь завершения копирования]

Как исправить

Убрать "прослойку"

Нагромождение падежей, созданное "прослойкой"

Комментарий

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

Примеры

Сочетание "с именем вида AVPyymm.AVC" означает 'с именем, построенным по модели AVPyymm.AVC', - тогда как возникает соблазн трактовать его: 'с именем вида, звучащим как AVPyymm.AVC'.

Как исправить

Перестроить конструкцию в целом

Тяжеловесные конструкции с отглагольными существительными

Комментарий

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

Примеры

Для установки программы на Ваш компьютер, выполните следующий ряд действий... [следовало бы: Для того чтобы установить программу на Ваш компьютер, выполните следующий ряд действий...]

Как исправить

Заменить конструкцию с отглагольным существительным на конструкцию с глаголом

Многократный родительный падеж

Комментарий

Весьма часто встречается в технических текстах

Примеры

Название контейнера получателей сервера

Средства обеспечения взаимодействия устройств автоматической смены накопителей

Средства обеспечения согласованного взаимодействия устройств автоматической смены накопителей

Как исправить

Некоторые из родительных падежей можно заменить синонимическими конструкциями

Неправильное управление

Комментарий

Иногда существительное, зависимое от глагола или другого существительного, ставится автором не в том падеже в котором требуется правилами грамматики.

Примеры

Удалить вирусы непосредственно внутри [надо: из] архива

Электронный адрес, на который [надо: по которому] программа будет посылать...", а "электронный адрес, по которому программа будет посылать...

Как исправить

Заменить падежную форму

Неправильное согласование

Комментарий

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

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

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

Примеры

Если в заголовке заявлена тема: "Ввод имени и адреса пользователя", то и в тексте раздела словом "пользователь" должно фигурировать в единственном числе.

Как исправить

Заменить согласуемую форму

Избыток причастных оборотов и придаточных

Комментарий

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

Как исправить

См. п. 4.3.5

Неверная модальность

Комментарий

Очень часто глаголы ставятся в неподобающей модальности. Либо подчеркивается жесткое долженствование: "Вам необходимо", "Вам следует", "Вы должны", - либо возникает, напротив, сослагательное наклонение с его чрезмерной вежливостью: "Если бы Вы хотели...".

Как исправить

Заменить модальное слово на рекомендуемое в п. 4.4

Употребление стилистически окрашенного слова

Комментарий

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

Как исправить

Заменить слово на нейтральное по стилю

Оскорбительные, неприятные и смешные ассоциации

Комментарий

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

Как исправить

Переработать фразу

Плеоназм

Комментарий

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

Примеры

Сервисные услуги

Как исправить

Заменить на правильное выражение

Тавтология --

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

Наименование ошибки

Повторы союзов и предлогов

Комментарий

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

Как исправить

Разбейте фразу на две самостоятельные или замените один из союзов на синонимическую конструкцию

Повторы значимых слов

Комментарий

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

Примеры

Для того чтобы установить цвет фона, нажмите на кнопку "Цвет фона", после чего в диалоговом окне "Цвет фона" выберите в списке "Цвет фона" цвет фона

Как исправить

Заменить значимое слово синонимом или местоимением

Повторы однокоренных и созвучных слов

Комментарий

Как стилистический дефект звучат близкие сочетания однокоренных или созвучных слов:

Примеры

Следует следить Позволяет пользователю пользоваться

При применении

И имеет

На наличие

Как исправить

Заменить одно из слов синонимом или переработать всю конструкцию

Дефекты ритмики

Комментарий

Можно выделить два случая: Под ударением два или несколько раз оказывается одно и то же слово. Возникновение "поэтического" звучания текста - избыточная ритмичность, внутренняя рифма

Примеры

Для того чтобы изменить настройки, хранящиеся в файле настройки Включение и отключение режима лечения

Как исправить

Заменить одно или несколько из повторяющихся слов синонимами. Перестроить фразу в другом ритме.

Неблагозвучные сочетания

Комментарий

В тексте документации не должно быть неблагозвучных сочетаний: скоплений согласных (более 3-4), скоплений гласных (более 2), скоплений шипящих и свистящих, неприятных звуковых ассоциаций.

Слова-паразиты и конструкции-паразиты

Наименование ошибки

Слова-указатели

Комментарий

Существует ряд слов, которые авторы иногда употребляют вместо того, чтобы подробно и конкретно охарактеризовать или описать элемент программного продукта. Мы обобщенно называем их дейктическими словами, или словами-указателями. Это слова, которые не обозначают предмет речи, а лишь указывают на него: "при этом", "при том", "данный", "соответствующий" и пр.

Как исправить

Заменить слово-указатель на полнозначное слово или поясняющую конструкцию.

Конструкции-иероглифы

Комментарий

В документации встречаются слова и конструкции, которые не имеют самостоятельного значения, а маркируют высказывания определенного типа (см. Примечание 2). Они повторяются много раз и отвлекают внимание пользователя.

Примеры

"Вы можете" как зачин при перечислении ряда пользовательских возможностей [вместо этого следовало бы написать один раз "Вы можете", а затем дать перечисление]

Несколько фраз в документации выглядят как "В поле <наименование поля> задается <тип задаваемых данных>"

Как исправить

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

Примечания

1. Валентность слова - это синтаксическая связь, которая для этого слова должна реализоваться в обязательном порядке. Например, слово "жить" имеет только одну валентность: "кто", слово "просвещать" - две валентности: "кто" и "кого". Невозможно сказать просто: "Он просвещает".
2. Конструкции-иероглифы напоминают символы бюллетеня рядом со смысловой рубрикой. Например, если в разделе перечисляются возможности пользователя и напротив каждой значится "Вы можете", то "Вы можете" - это конструкция-иероглиф. Для смысла текста не имеет значения, напишет автор напротив каждой опции "Вы можете" или поставит значок перечисления.