В одном из произведений Хорхе Луиса Борхеса упоминается фантастическая "некая китайская энциклопедия", в которой все животные подразделяются на следующие группы: a) принадлежащие Императору; b) бальзамированные; c) прирученные; d) молочные поросята; e) сирены; f) сказочные; g) бродячие собаки; h) включенные в настоящую классификацию; i) буйствующие, как в безумии; k) неисчислимые; l) нарисованные тонкой кисточкой из верблюжьей шерсти; m) только что разбившие кувшин; n) издалека кажущиеся мухами.

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

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

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

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

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

Документация к программному продукту в данном отношении не только не является исключением, но напротив, - одним из типичных случаев. Размещение сведений о продукте в технической документации определяется двумя названными в п. 3.1 факторами:

• Общей логикой изложения
• Соображениями удобства

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Составление заголовков, строго говоря, относится уже к этапу словесного воплощения замысла. Мы, однако, разместили эту тему здесь, поскольку заголовки разделов:

• Играют значительную роль в структурировании информации.
• Делают более очевидной общую структуру документации.
• Облегчают чтение документации и поиск в ней необходимых сведений

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

Как правило, заголовок состоит из одной фразы (словосочетания) и коротко обозначает тему раздела, "реферирует" его содержание. Такой порядок составления заголовков восходит к глубокой древности. Ему противостоит другой, не менее древний, когда текст озаглавливался по нескольким первым словам (как, например, во многих древнееврейских текстах). Эта вторая традиция характерна для тех культур, которые все время вращаются в кругу одних и тех же текстов и используют их не столько в информационных, сколько в ритуальных, богослужебных, медитативных и тому подобных целях; эти тексты людям надо просто отличать один от другого.

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

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

Из этого вытекают и критерии качества заголовков к технической документации.

Заголовок должен быть не слишком длинным.

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

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

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

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

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

Например:

• Действия с зараженными объектами
• Действия с испорченными вирусом объектами
• Действия с подозрительными объектами

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

Лучше так:

• Зараженные объекты и действия с ними
• Испорченные вирусами объекты и действия с ними
• Подозрительные объекты и действия с ними

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

1. Назывное предложение. Состоит из главного слова - имени существительного, иногда в сопровождении поясняющих его зависимых слов. Например: "Файлы", "Файлы, зараженные вирусом", "Файлы с расширением .doc". Часто несколько главных слов соединены сочинительной связью (соединены союзом И или перечисляются через запятую). Например: "Файлы и папки", "Файлы, папки и вложенные папки".
2. Предложное сочетание: "О"+тематическое слово (существительное). Тематическое слово имеет при себе поясняющие зависимые слова; несколько тематических слов могут быть соединены отношениями перечисления. Например: "О программном комплексе "Ресурсная смета"", "Об операционной системе Microsoft Windows 3000 и ее возможностях".
3. Заголовок-"вопрос". Представляет собой предложение, начинающееся с вопросительного местоимения (как правило, "как") и содержащее "вопрос", на который призван ответить раздел. Например: "Как отформатировать дискету".

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

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

Употребление "назывных" заголовков практически не имеет ограничений, но иногда порождает неуклюжие синтаксические конструкции:

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

• Нагромождения родительных падежей.

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

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

Заголовок-"вопрос" употребителен в следующих случаях:

• Раздел отвечает на некий важный, ключевой вопрос, который естественным порядком возникает у большинства пользователей. Например: "Как быстро начать работать с..." вместо малопонятного "Быстрый старт" (калька с "Quick start").
• Раздел дает не полное описание проблемы, а лишь предельно конкретной процедуры. Например: "Форматирование дискеты" (подробно излагаются все связанные с этим аспекты), но: "Как отформатировать дискету" (описывается конкретная процедура).

Заголовок-"вопрос" имеет следующие недостатки:

• Не всегда позволяет уловить главное в теме.

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

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

Например: "Разметка текста. Блоки".

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