Информационная технология. Процесс создания документации пользователя программного средства - [8]

8.1.7 Контроль изменений и сопровождение документации

8.1.7.1 Общие положения

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

a) функциональные изменения данной версии (this-version function changes) — изменения функции программного средства, внесенные при разработке документации и отраженные в опубликованной документации;

b) функциональные изменения последующей версии (next-version function changes) — изменения функции программного средства, внесенные при разработке документации и не отраженные в опубликованной документации, но подлежащие учету в последующей редакции документации.

Примечание — Различие между перечислениями а) и b) обычно определяется термином «дата пересмотра (cut-off date)»;

c) изменения программного средства после публикации (post-publication software changes) — изменения конкретных функций программного средства после издания данной документации;

d) изменения документа после публикации (post-publication document changes) — изменения в опубликованной документации, обусловленные изменениями программного средства или обнаружением погрешностей в данной документации.

8.1.7.2 Процедуры

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

a) была предусмотрена процедура внесения каждого типа изменений в документ.

Примечание — Разработчики документации обычно должны получать учтенные копии изменений программного средства, подтверждающие внесение соответствующих изменений в данное средство после конкретной даты его пересмотра;

b) наименование документа и номер версии или дата были указаны в верхнем или нижнем колонтитуле конкретного документа;

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

d) дополнительно были предусмотрены методы, обеспечивающие внесение изменений в каждую учтенную копию конкретного документа;

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

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

8.2 Содержание спецификации стиля

8.2.1 Общие положения

В данном подразделе определено содержание спецификации стиля документации.

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

8.2.2 Стиль описания

8.2.2.1 Язык

Должен быть указан язык, на котором составлена документация для конкретной страны, например французский (для Канады).

8.2.2.2 Орфография

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

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

8.2.2.3 Грамматика и ее применение

Должны быть приведены рекомендации по грамматике языка и стилю ее применения.

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

8.2.3 Бумажная документация

8.2.3.1 Компоновка и оригинал-макеты

8.2.3.1.1 Размер (формат) бумаги

Должен быть определен используемый размер бумаги.

Примечание — При выборе размера бумаги должно быть учтено следующее:

a) форматы А4, А5 и В5 указаны в настоящем стандарте (см. 4.1 и 4.5);

b) как будут храниться данные документы (в некоторых архивах возникают проблемы с хранением документов в конкретных форматах);

c) используются ли распечатки экранов (распечатки целых экранов в формате А5 недостаточно разборчивы);

d) используемый национальный стандартный формат бумаги, если документация представляется в виде фотокопий;

e) требования к мобильности и рабочей области документации.

8.2.3.1.2 Ориентация (расположение)

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

8.2.3.1.3 Одно- или двусторонняя печать

Следует указать, будет ли документация печататься в одно- или двустороннем формате.

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

8.2.3.1.4 Разрешающая способность типографского или лазерного способа печати