Документирование программного продукта

содержание

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1. Документирование программного продукта. Структура документации. Стандартизация программной документации (ЕСПД). Централизованный фонд алгоритмов и программ (ЦФАП). Передача программных средств в ЦФАП.

Документирование  программного продукта.

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

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

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

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

Чтобы ответить на вопрос, для чего составляется документация к программному продукту, необходимо понять, (1) кем, (2) для чего и (3) как она используется.

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

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

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

Пример: бухгалтерские программы, текстовые и графические редакторы.

• Существенно расширит круг его возможностей в части решения практических задач.

Пример: издательские системы, базы данных.

• Создаст для него принципиально новую привлекательную сферу деятельности.

Пример: игровые программы, программы  для работы в Internet.

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

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

3. Как используется документация? Из сказанного выше очевидно, что она используется для поиска и получения информации. Однако существуют различные сценарии поиска информации, и соответственно, использования документации. Предсказывая возможные варианты поведения пользователя, можно свести эти сценарии к нескольким основным:
• "Быстрый старт", т. е. поиск сведений об установке, настройке, запуске и начале работы с программным продуктом.
• Ознакомительное чтение, дающее возможность освоить работу с продуктом в целом и способы решения наиболее типичных практических задач.
• Целевой поиск путей решения той или иной конкретной практической задачи с помощью продукта.
• Запрос и получение исчерпывающей справочной информации по избранному режиму(ам), элементу(ам) интерфейса, функции(ям) и т. д.
• Детальное знакомство с программным продуктом и нюансами его работы.

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

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

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

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

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

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

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

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

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

Структура документации.

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

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

Размещение сведений о продукте в технической документации определяется двумя факторами:

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

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

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

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