В п. 3.2 и п. 3.3 мы рассматривали вопросы рационального размещения в тексте документации информации различного содержания. Однако существует и другая, также очень важная проблема - рациональное размещение информации различного характера. Дело в том, что текст документации неоднороден; он состоит из основного текста, на фоне которого обособляются сведения, которые мы называем выделенными. К выделенным сведениям относятся:

• Выделенные сообщения.
• Выделенные элементы.

К выделенным сообщениям относятся:

• Инструкция, или описание процедуры.
• Определение.
• Совет.
• Замечание.
• Предупреждение.
• "Строгое" предупреждение.

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

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

Стили графического оформления выделенных сообщений включены в корпоративный стандарт фирмы "Философт" и перечислены в документе "Стандартные стили графического оформления технической документации"*.

К выделенным элементам относятся:

• Вновь вводимые (впервые употребляемые) термины.
• Фрагменты экранного текста (см. Примечание 1).
• Названия элементов интерфейса.
• Названия клавиш и их "горячих" комбинаций.

В состав выделенных сообщений могут входить выделенные элементы.

Стандартные стили оформления выделенных элементов включены в корпоративный стандарт фирмы "Философт" и перечислены в документе "Стандартные стили графического оформления технической документации"*.

Выделенные сведения (сообщения и элементы) играют двоякую роль в рациональном размещении информации:

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

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

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

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

Определения даются перед или сразу после первого упоминания термина. Они имеют четкую синтаксическую структуру по следующему образцу:

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

Определения описанного типа мы называем явными. Явное определение нужно уметь осмыслить, для этого часто требуется дополнительное напряжение умственных сил. Так, в приведенном нами примере предполагается, что пользователь хорошо представляет себе: что такое программа, что такое копия программы (да и еще и "не обязательно в точности повторяющая оригинал"!), и как ее можно "внедрять в объекты и/или ресурсы", и многое другое. Далее, за пользователем предполагается умение собрать все эти понятия воедино и применять определение к объектам реальности. Все это требует определенных навыков, которыми реальный пользователь обладает далеко не всегда; во всяком случае, Вы не всегда имеете право рассчитывать на это.

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

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

Очевидно, что, так или иначе, пользователь должен получить представление о смысле терминов, которыми ему (вместе с Вами) предстоит оперировать. Вы должны решить, какие из терминов Вы считаете известными пользователю, какие должны, на Ваш взгляд, получить неявное определение, какие - явное. Это распределение в каждом конкретном случае зависит от квалификации потенциального пользователя, его знакомства с версиями или аналогами продукта и т. д. Вопросы явного или неявного определения терминов (либо их использования, по умолчанию, как известных) решаются по мере формирования терминологии документации (об этом подробнее см. п. 4.2.1). Здесь для нас важно следующее: термину может быть дано:

• Явное определение - дается в виде выделенного сообщения перед или сразу после первого упоминания термина.
• Неявное определение - дается прямо в основном тексте перед или сразу после первого упоминания термина.
• Может не даваться никакого определения.

Во всех трех случаях первое упоминание термина маркируется как выделенный элемент.

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

Замечание помещается:

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

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

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

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

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

Графически пункты перечисления даются в виде списка с простыми символами бюллетеня (жирными круглыми точками · ).

Графический стиль, которым оформляется перечисление, включен в корпоративный стандарт фирмы "Философт" и приведен в документе "Стандартные стили графического оформления технической документации"*.

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

Примечания

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