Читатель, вероятно, уже заметил, что мы используем попеременно то слово "документация", то слово "документ" (слово "технический, техническая, техническое" мы в дальнейшем будем часто опускать, поскольку и так очевидно, о какого рода текстах идет речь). Между ними, однако, есть существенная разница. Документом называется связный, единый, завершенный текст, соотнесенный с одним из видов документов: руководством пользователя, справочником пользователя и т. д.; документация - понятие собирательное, она состоит из ряда документов. Однако часто бывает так, что документация к программному продукту вся собрана под одной обложкой и представляет собой интегрированный документ. Мы говорим о главах и разделах документации, имея в виду этот единый документ.

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

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

В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User's Guide и User's Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника. Руководство и справочник - это не столько части документации, сколько понятия, которые воплощают собой два подхода к описанию программного продукта.

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

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

Все остальные части либо подготавливают читателя к осмысленному чтению двух стержневых, либо содержат вспомогательную и специфическую информацию. Они, как правило, существуют в интегрированном виде вместе с руководством или справочником пользователя. Документация обычно снабжается рядом приложений, а также оснащается аппаратом: указателем (индексом), глоссарием, перекрестными ссылками* (см. Примечание 1). О структуре документации см.. п. 3.2.1 и п. 3.2.2.

Особняком стоит еще один тип документа - справочный гипертекст, на основе которого функционирует система справок по программе (Help). Гипертекст, как правило, пишется на основе готовой "бумажной" документации; в то же время его ни в коем случае не следует рассматривать лишь как слегка модифицированный обычный текст. Отдельные части гипертекста связаны настолько сложной системой реализуемых в интерактивном режиме взаимных ссылок, что необходимо уже говорить о гипертексте как о совершенно специфическом средстве передачи информации со своими законами, отличными от законов обычного текста. Эта специфика гипертекста выражается, что очень важно для нас, в кардинальном расширении возможностей передачи информации по сравнению с обычным текстом. Более подробно о гипертексте справки см.: "Гипертекст"*. В настоящем Руководстве речь пойдет о "бумажной" документации. Мы будем рассматривать ее как единый документ с определенной четкой и строгой стандартной структурой.

* * *

Мы очертили круг основных компонентов, из которых складывается готовая документация, - в том виде, в каком с ней встречается пользователь (и в каком с ней наверняка встречались и Вы). Однако разработчик документации начинает, разумеется, не с готовой книжки, а с чистой рабочей панели текстового редактора (см. Примечание 2). Наша задача не столько в том, чтобы рассказать, как выглядит документация, сколько в том, чтобы дать конкретные рекомендации по ее разработке. Всем известно, какие проблемы возникают в процессе написания связного текста большого объема - как приступить к работе, с чего начать, как расположить материал.

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

• Какие цели преследует разработчик документации к программному продукту?
• Какими средствами он располагает для достижения своих целей?

Примечания

1. Знаком * обозначаются те темы или понятия, которые предполагается осветить во второй части Руководства или в особых документах.
2. Разумеется, это не совсем так, если разработчик занят обновлением и/или модифицированием уже существующей документации, например создает на ее базе документацию к новым версиям программного продукта и т. д. В этом случае он работает с отчасти уже готовым текстом. Все же мы будем рассматривать ситуацию “чистого листа” в качестве базовой, а остальные ситуации — как вторичные по отношению к ней.