Р ИСО/МЭК 15910-2002 Процесс создания документации пользователя программного средства

Home » Библиотека » Стандарты » Оформление проектных документов » ГОСТ P » Р ИСО/МЭК 15910-2002 Процесс создания документации пользователя программного средства

ГОСТ Р ИСО/МЭК 15910-2002 ГОСУДАРСТВЕННЫЙ СТАНДАРТ РОССИЙСКОЙ ФЕДЕРАЦИИ

Информационная технология

ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ

ПРОГРАММНОГО СРЕДСТВА

Издание официальное

ГОССТАНДАРТ РОССИИ М о с к в а

Предисловие

1 РАЗРАБОТАН И ВНЕСЕН Всероссийским научно-исследовательским институтом стандартиза¬ции (ВНИИстандарт) Госстандарта России
2 ПРИНЯТ И ВВЕДЕН В ДЕЙСТВИЕ Постановлением Госстандарта России от 25 июня 2002 г. № 249-ст
3 Настоящий стандарт содержит полный аутентичный текст международного стандарта ИСО/МЭК 15910—99 «Информационная технология. Процесс создания документации пользователя программного средства»
4 ВВЕДЕН ВПЕРВЫЕ
© ИПК Издательство стандартов, 2002

Содержание

Введение

Существующие стандарты можно отнести к двум основным типам:
a) стандарты на продукцию, определяющие ее характеристики и требования к ней;
b) стандарты на процессы, определяющие конкретные методы создания продукции.
Возрастающий масштаб применения программных средств и их сложность вызывает необходи¬мость наличия полной, точной и понятной документации на эти средства, доступной пользователям. Настоящий стандарт определяет способ достижения данной цели, устанавливая работы (что должно быть сделано и исполнителя), связанные с качеством документации пользователя программных средств.
Документация часто рассматривает нечто, разрабатываемое после создания конкретного про¬граммного средства. Однако с точки зрения качества разработки программной документации она должна рассматриваться как неотъемлемая часть процесса создания данного программного средства. При надлежащем подходе к данной проблеме требуется достаточно сложная работа по планированию документирования. Целью настоящего стандарта является стимулирование разработчиков программных средств к надлежащему использованию процесса документирования. Стандарт также представляет пользо-вателям метод определения надлежащего применения процесса документирования при создании конк-ретного программного средства.
Основной работой по настоящему стандарту является создание комплексного плана разработки документации, реализация которого обеспечивает лучшее документирование программного средства. Для соответствия настоящему стандарту данный план должен включать в себя требования (специфика¬цию) к стилю оформления документов. Настоящий стандарт не определяет состав данных требований (то есть компоновку конкретного документа или используемый шрифт), но устанавливает их диапазон. Стандарт также определяет виды информации, представляемой заказчиком разработчику документа¬ции (документатору) для проверяющих и распространяющих документацию.
Более подробная информация по данному вопросу приведена в библиографии.

П р и м е ч а н и я
1 Основной стандарт дополнен справочными приложениями, библиографией и тематическим указате¬лем.
2 Исходный стандарт ИСО/МЭК 15910 разработан на основе австралийского стандарта AS 4258:1994.
3 Перечень дополнительных публикаций, связанных с тематикой настоящего стандарта, приведен в библиографии (см. [1] — [21]).
Информационная технология
ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА
Information technology. Software user documentation process
Дата введения 2003—07—01

1 Область применения

Настоящий стандарт определяет минимально необходимый процесс создания документации пользо-вателя всех видов для программного средства, имеющего интерфейс пользователя. Данные виды охва¬тывают печатную документацию (например, руководства пользователя и краткие справочные карты), диалоговую (оперативную) документацию, справочный текст («хелпы») и системы диалоговой доку¬ментации.
Стандарт соответствует требованиям 6.1 ГОСТ Р ИСО/МЭК 12207.
Применение настоящего стандарта должно обеспечить разработку документации, удовлетворяю¬щей потребностям пользователя.
Стандарт предназначен для разработчиков и потребителей документации пользователя.
Настоящий стандарт используется для печатной документации, а также для справочных экранов, справочной системы обеспечения поставки, справочной информации и т. д.
Стандарт предназначен для применения при двусторонних отношениях и может быть использо¬ван, если обе стороны корпоративно связаны. Стандарт также может быть использован одной из сторон для самоконтроля.

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

2 Соответствие

Соответствие настоящему стандарту определяют по результатам демонстрации выполнения реали-зацией процесса, описанного в разделе 8.

3 Нормативные ссылки

В настоящем стандарте использованы ссылки на следующие стандарты:
ГОСТ 2.301—68 Единая система конструкторской документации. Форматы
ГОСТ Р ИСО 9127—94 Системы обработки информации. Документация пользователя и инфор¬мация на упаковке для потребительских программных пакетов
ГОСТ Р ИСО/МЭК 12119—2000 Информационная технология. Пакеты программ. Требования к качеству и тестирование
ГОСУДАРСТВЕННЫЙ
СТАНДАРТ
РОССИЙСКОЙ ФЕДЕРАЦИИ
ГОСТ Р ИСО/МЭК 12207—99 Информационная технология. Процессы жизненного цикла про-граммных средств
ИСО 216—75* Бумага писчая и классы печатных материалов. Размеры обрезки. Серии А и В.
* Оригинал международного стандарта — во ВНИИКИ Госстандарта России. Издание официальное

4 Определения

В настоящем стандарте использованы следующие термины с соответствующими определениями.
4.1 А4, А5: Размеры сторон листа 210297 мм и 148210 мм соответственно (см. ИСО 216, ГОСТ 2.301).
4.2 заказчик (acquirer): Организация, которая приобретает или получает систему, программный продукт или программную услугу от поставщика (3.1 ГОСТ Р ИСО/МЭК 12207).
П р и м е ч а н и е — Заказчиком может быть: оптовый или розничный покупатель, клиент, собственник или пользователь. В контексте настоящего стандарта заказчиком является сторона, запрашивающая докумен¬тацию. Отметим, что наличие у заказчика документации не является обязательным. Заказчик и разработчик документации могут быть представителями одной организации, или заказчиком может быть разработчик дан¬ного программного средства.
4.3 аудитория (audience): Категория пользователей, предъявляющих к документации одинаковые или аналогичные требования и характеристики (например, в части использования документации, ее назначения, уровня обучения, возможностей и опыта персонала), определяющие содержание, струк¬туру и назначение данной документации.
П р и м е ч а н и е —Одна и та же программная документация может использоваться различными аудиториями (например, руководством, операторами по вводу исходных данных или сопроводителями).
4.4 изучение аудитории (audiеnce research): Планируемый процесс опроса потенциальных пользо-вателей и анализа его индивидуальных и интегральных результатов.
П р и м е ч а н и е — Целью данного процесса является определение возможностей, квалификации, опыта, предубежденности и преимуществ потенциальных читателей документа.
4.5 В5: Размеры сторон листа 176250 мм (см. ИСО 216).
4.6 вспомогательный материал (back matter): Материал, содержащийся в конце книги или руко-водства, например, тематический указатель.
4.7 фотошаблоны (camera-ready originals):Hабор изображений на бумаге, фотопленке или другом носителе, с которого может быть сделана фотокопия, где каждое изображение содержит все необходи¬мые текстовые и графические элементы одной страницы печатного документа. скомпонованные долж¬ным образом.
4.8 дата пересмотра (cut-off date): Дата, по истечении которой все изменения, внесенные в программные средства, описываются в новой редакции документации, более верной по сравнению с действующей.
4.9 номенклатура поставки (deliverables): Объекты (элементы, изделия и т. д.), поставляемые заказчику по условиям договора.
4.10 документ (document): См. элемент документации (4.26).
4.11 документация (documentation): Печатные руководства пользователя, диалоговая (оператив¬ная) документация и справочный текст («хелпы»), описывающие как пользоваться программным продуктом.
4.12 персонал разработчиков документации (documentation development staff): Весь персонал, привлекаемый на любом этапе планирования, написания, редактирования и выпуска документации.
П р и м е ч а н и е — Данный термин охватывает коллектив авторов, оформителей, иллюстраторов и администрации проекта.
4.13 план документирования (documentation plan): Документ, в котором излагаются необходимые элементы проекта документирования.
4.14 документатор (documenter): Сторона, создающая документацию.
П р и м е ч а н и е — В настоящем стандарте не используют термин разработчик (developer) (в смысле 3.8 по ГОСТ Р ИСО/МЭК 12207), так как в случае документирования разработчик программного средства часто является заказчиком документации, и использование термина разработчик может привести к разночтению. Поэтому используют термин документатор.
4.15 электронная копия (electronic copy): Компьютерный диск или другой машиночитаемый носитель информации, содержащий файл или файлы, с которого(ых) может быть распечатан доку¬мент.
4.16 n-штрих (en dash): Штрих, имеющий такую же ширину, как и строчная буква «n».
4.17 концевые примечания (endnotes): Примечания, собранные в конце главы или документа.
4.18 страница-раскладка (foldout): Страница, сложенная так, что ее задняя часть шире передней (немного превышает основной формат), которую можно развернуть.
4.19 нижний колонтитул (footer): Справочная(ые) строка(и) под текстом страницы, указываю¬щая^) на ее содержание (например, номер страницы).
4.20 сноска (footnote): Помещаемый внизу страницы (колонки) текст (примечание, библиогра¬фическая ссылка и т. д.), связанный с основным текстом знаком сноски (цифровым номером, звездоч¬кой), закрываемым круглой скобкой, набираемый обычно шрифтом пониженного кегля по сравне¬нию со шрифтом основного текста и отделяемый от него пробелом или пробелом с тонкой короткой линейкой.
4.21 вводный материал (front matter): Начальная часть или глава издания, например, титульный лист и содержание.
4.22 верхний колонтитул (header): Справочная(ые) строка(и) над текстом страницы.
4.23 заголовок (heading): Название внутреннего подраздела издания, определяющее тему, рас-крываемую в последующем тексте.
4.24 справочная система (help system): См. 4.32.
4.25 справочный текст (help text): Текст, облегчающий и убыстряющий пользователю, при экс-плуатации программного средства, поиск содержащихся в издании объектов, автоматически выбирае¬мый в зависимости от контекста, в котором он вызывается, т. е. справочный текст контекстно зависим.
4.26 элемент документации (item of documentation): Целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в крат¬кой справочной карте) в заданном формате.
4.27 справочная ссылка (location reference): Метка, выделяющая заголовок или подзаголовок в тематическом (предметном) указателе, показывающая, к какой части документа они относятся.
4.28 измененный документ (изменение документа) (mark-up): Документ, содержащий заполнен¬ные листы изменений, а также процесс создания такого документа.
4.29 оригинал-макет (mechanicals): Оригинал, напечатанный как образец для набора, содержа¬щий подробные текстовые, переплетные, издательские и компоновочные характеристики печатной продукции (издания).
4.30 навигация (navigation): Способ перехода пользователя от одной части прикладных программ¬ных средств к другой.
4.31 диалоговая документация (on-line documentation): Информация, доступная пользователю при эксплуатации программного средства, которая не обязательно привязана к конкретному контексту (см. также 4.25).
4.32 система диалоговой документации или справочная система (on-line documentation system or help system): Часть программы (иногда отдельная программа), запрашиваемая пользователем и позво¬ляющая ему просматривать части диалоговой документации или справочного текста (см. также 4.25 и 4.31).
4.33 концевая висячая строка (orphan): Строка части текста (главы, раздела и т. д.) единственная на странице (полосе).
4.34 бумажный документ (orphan): Часть документации, представляемая в печатном виде.
4.35 элиз (доп. пиксель) (pixel): Наименьший элемент изображения на экране дисплея; сокраще¬ние от «элемент изображения» («picture element»).
4.36 точка (point): Единица типометрической типографской системы, выражаемая расстоянием по вертикали и содержащая в 1 мм приблизительно 2,8 точек (в одном дюйме приблизительно 72 точки).
4.37 процесс (process): Набор преобразующий исходные данные в выходные результаты (3.17 ГОСТ Р ИСО/МЭК 12207).
4.38 продукция (product): Полный набор компьютерных программ, процедур и соответствующих им документации и данных, предназначенный для поставки пользователю.
П р и м е ч а н и е — Используют также термин «программный продукт».
4.39 производство (production): Предварительная подготовка текста к переводу его в фотошабло¬ны, законченные справочные тексты или диалоговую документацию.
4.40 гранки (proof): Окончательная редакция бумажного документа, представленная перед печа¬тью заказчику для рассмотрения и утверждения.
П р и м е ч а н и е — При отсутствии замечаний окончательный документ должен быть во всех отноше¬ниях идентичен гранкам, за исключением вида бумаги, переплета и цветового оформления. Гранки обычно являются фотокопией фотошаблонов.
4.41 прототип (prototype): Модель или предварительная реализация части программного средства, пригодная для оценки проекта системы, ее потенциальных рабочих характеристик, производства или лучшего понимания требований к программному средству.
4.42 оборот (листа) (recto): Страница нижняя по отношению к левой или правой верхней стороне крышки переплета.
4.43 распечатка экрана (screen dump): Предполагаемое изображение, которое пользователь дол¬жен видеть на экране при эксплуатации программного средства.
4.44 система (system): Комплекс процессов, технических и программных средств, устройств, обслуживаемый персоналом и обладающий возможностью удовлетворять установленным потребностям и целям (3.31 ГОСТ Р ИСО/МЭК 12207).
4.45 содержание (table of contents): Указатель заголовков издания с указанием номеров страниц в порядке их возрастания.
4.46 таблица действующих страниц (лист изменений) (table of effective pages): Перечень последних версий номеров каждой замененной страницы бумажного документа. При замене отдельных страниц в перечне указывают старые и новые номера страниц.
4.47 план выбора группы проектантов (team selection plan): Документ, устанавливающий требова¬ния к квалификации и опыту персонала, разрабатывающего документацию.
4.48 страница-развертка (throwclear): Страница-раскладка, выполненная таким образом, что в развернутом виде и закрытом издании (книге, руководстве) доступна для обозрения (чтения) совме¬стно с предыдущими страницами.
4.49 практическая лаборатория (usability laborato^): Комплекс аналитических и исследовательс¬ких помещений, оснащенных видео- и аудиооборудованием для регистрации ответов на запросы пользо¬вателей.
4.50 тестирование на практичность (usability testing): Формальный процесс оценки соответствия документации установленным требованиям.
4.51 интерфейс пользователя (user interface): Интерфейс, обеспечивающий возможность обмена информацией между человеком и техническими или программными компонентами вычислительной системы.
4.52 пользователь (user): Лицо или организация, которые используют действующую систему для выполнения конкретной функции (3.34 ГОСТ Р ИСО/МЭК 12207).

П р и м е ч а н и е — см. также 4.3.
4.53 разворот (листа) (verso): Две смежные страницы раскрытого издания, левая и правая.
4.54 разделитель активный (white space, active): Пространство (за исключением полей), охватыва¬ющее текстовые и графические элементы, разделяющее текст, отделяющее тематические и подтемати- ческие составляющие текста, указывающее в тексте тематические и иерархические отношения, выде¬ляющее соответствующую информацию и облегчающее чтение текста.
4.55 разделитель пассивный (white space, passive): Верхнее, нижнее, левое и правое поля, окружа¬ющие текст.
4.56 начальная висячая строка (widow): Первая строка части текста (главы, раздела и т. д.), завершающая последнюю строку на странице (полосе).

5 Управление качеством

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

П р и м е ч а н и е — Даже если стандарт по управлению качеством не указан в договор (контракте), документаторы стремятся использовать систему управления качеством, аттестованную на соответствие дан- ному(ым) стандарту(ам). Относительно качества программного средства в целом см. ГОСТ Р ИСО/МЭК 12119.

Адаптация
Настоящий стандарт определяет одну из реализаций процесса документирования, описанного в ГОСТ Р ИСО/МЭК 12207, и может быть адаптирован к условиям конкретных проектов (см. приложе¬ние В).

Цели
Настоящий стандарт по существу является стандартом на процесс. Стандарт не определяет компо¬новку конкретного документа, его содержание и другие аспекты комплектности документации, одна¬ко он устанавливает метод планирования и проведения процесса документирования.

Требования
8.1 Процесс документирования
8.1.1 О б щ и е п о л о ж е н и я
Процесс документирования должен быть выполнен в два этапа в последовательности, представ¬ленной на рисунке 1 в затененных прямоугольниках. Поэтапные работы не выполняются одновременно. На отдельных этапах работы могут проводиться параллельно. Возможные итерации работ показаны пунктирными линиями.
Когда минимальный состав документации определяется заказчиком (например, с использова¬нием ГОСТ Р ИСО 9127 или ИСО/МЭК 6592 [1]), это должно быть учтено документатором при разработке плана документирования.
8.1.2 П р е д с т а в л е н и е и с х о д н ы х м а т е р и а л о в
Заказчик должен обеспечивать документатору доступ:
a) ко всем соответствующим спецификациям, форматам записей, компоновкам экранов и отче¬тов, выходным результатам работы средств автоматизации программирования (САSE tool) и другой информации, необходимой для подготовки документации;
b) к рабочей копии программного средства (при необходимости);
c) к аналитикам и программистам, включая своевременное правильное решение вопросов, воз-никающих у персонала разработчиков документации;
d) к типичным пользователям (по возможности) для анализа аудитории и тестирования на практичность.
В обязанности документатора входит обеспечение плодотворности контактов с разработчиками программных средств заказчика, гарантирующее как минимум понимание сути выпускаемой продук¬ции и соответствующих ей аудиторий.
П р и м е ч а н и е — Документатор не отвечает за разработку, проверку или корректировку исходных материалов, а только за их получение.
Независимо от того, является ли документатор одновременно разработчиком программного сред¬ства, заказчик должен обеспечить его копиями всех применяемых стандартов, руководствами по сти¬лям и форматам, а также соответствующими материалами (если они не являются общедоступными). Документатор должен обеспечить данными материалами соответствующий персонал разработчиков документации.
Обязанностью разработчика является обеспечение полноты, правильности и актуальности всех материалов, предъявляемых разработчику на момент их поставки.
Разработчик должен гарантировать, что представление документатору данных материалов не на¬рушает прав интеллектуальной собственности любой третьей стороны.
Документатор должен предпринять соответствующие шаги по сохранению материалов, представ-ленных заказчиком, обеспечить защиту информации о требованиях заказчика и возвратить все мате¬риалы заказчику по завершении проекта документирования.
П р и м е ч а н и е — В ряде случаев нет необходимости возвращать все материалы; данный вопрос должен быть оговорен в договоре. В ряде случаев требуется сохранить конфиденциальность и секретность пре¬доставленных материалов. В договоре должны быть установлены уровни (грифы) конфиденциальности или секретности материалов, представляемых заказчиком документатору.

Рисунок 1 — Обзор процесса документирования

П р и м е ч а н и е — Обычно план документирования должен охватывать весь комплект документации, например руководства пользователя, диалоговую документацию, справочные тексты и краткие справочные карты. Пример плана приведен в приложении С. Процесс проектирования документации описан в приложе¬нии D.
В плане документирования должны быть четко описаны область применения и ограничения по использованию планируемой документации, а также основные решения по анализу и проектированию этой документации. В плане также должны быть определены процессы и проверки, выполняемые при разработке документации.
План документирования должен охватывать следующие вопросы (но не ограничиваться ими):
a) рабочее наименование, назначение, область применения и ограничения по использованию планируемой документации;
b) спецификацию стиля в соответствии 8.2;
c) определение аудитории пользователей (см. 8.1.3.2);
d) обоснование причин использования документации данной аудиторией и ее целевое назначение;
e) содержание (план-проспект) документации, с оценкой ее постраничного объема, и соответ¬ствующие уточнения для других машинных носителей документации;
f) номенклатуру поставки — число печатных копий, наличие электронных копий, форматы дисков и файлов (включая версии программных средств) и откуда они могут быть поставлены;
g) установление собственника авторских прав на документацию и любых других прав собствен¬ности.

П р и м е ч а н и е — Вопрос прав собственности является сложным. Во всех договорах на документацию должны быть указаны собственники соответствующих прав. При этом может быть указана последующая воз-можность передачи авторских прав от документатора к заказчику. Передача авторских прав целесообразна при определении места и способа тиражирования документации;
h) обеспечение перевода документации на другие языки.

П р и м е ч а н и е — Подробнее см. в приложении Е;
i) уровни (грифы) секретности и конфиденциальности (при необходимости);
j) процедуры и проверки, могущие влиять на процесс разработки документации, включая, при необходимости, хранение, поиск, резервирование, передачу и оценку качества;
k) методы и средства производства (тиражирования) и используемые версии данных средств;
l) структуру коллектива разработчиков документации и, возможно, плана выбора данной струк¬туры.

П р и м е ч а н и е — Конкретные лица привлекаются на различных этапах написания и производства (тиражирования) документации в зависимости от уровня своего опыта и знаний. Например, может быть необ-ходимым хорошее знание автором документируемой системы и опыт в написании документации; для редакто¬ра может потребоваться только опыт редактирования, но не знание системы; от компоновщика (оформите¬ля) может не требоваться других знаний кроме знания средств оформления;
m) взаимосвязи (подчиненности) проекта;
n) почасовую загрузку и зарплату персонала (руководство по оценке этих факторов приведено в приложении F);
0) требования к проектным ресурсам, включая информационные и прочие ресурсы, представ¬ляемые заказчиком, и срокам их представления;
р) метод передачи документатору информации об изменениях программного средства в процессе его разработки;
q) планы контроля изменений и сопровождения документации (факультативно);
r) планы проверки документации после ее создания;
s) календарное планирование (графики) по контрольным точкам (milestones), включая (при необходимости):
1) утверждение плана документирования,
2) подготовку, проверку и корректировку проекта каждого документа,
3) тестирование на практичность,
4) подготовку оригиналов фотошаблонов,
5) распечатку, переплетение и распространение документации.
При необходимости каждый из пунктов плана должен быть описан для каждого элемента доку-ментации.

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

П р и м е ч а н и я
1 Данные об определении аудитории пользователей могут быть получены из:
a) результатов изучения аудитории, проведенного заказчиком или документатором;
b) описаний, представляемых заказчиком;
c) определений аудитории, полученных из других источников.
2 По возможности персонал разработчиков документации должен организовать встречи с типовыми пользователями в их рабочей обстановке и обследовать их работу.
8.1.3.3 Контроль плана документирования
После официального согласования плана документатор должен нести ответственность за контроль и распространение данного плана. Документатором должен быть составлен список по распространению учтенных копий данного плана.
В случае внесения в план последующих изменений (согласованных документатором и заказчи¬ком) документатор должен гарантировать получение этих изменений всеми держателями учтенных копий.

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

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

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

П р и м е ч а н и я
1 Качество документации и успешность проверок повышаются при наличии хороших контактов между заказчиком и документатором в процессе разработки документации. При этом должно быть предусмотрено неформальное обсуждение возникающих вопросов и по возможности раннее представление заказчику образ¬цов документации или предварительных материалов.
2 Договор может быть скорректирован при необходимости внесения в него изменений, не связанных с областью действия договора или плана документирования.
3 Отметим, что проведение проверки не освобождает документаторов от обязанностей по гарантирова¬нию максимально возможной полноты и точности документации.
4 Непосредственно перед представлением любой публикации на утверждение, в ней должны быть обнов¬лены все распечатки экранов для гарантирования ее актуальности.
5 Результаты проверок представляются заказчиком документатору в виде пометок в проекте документа¬ции или письменных комментариев по его содержанию. Заказчик должен хранить копии всех вносимых измене¬ний для сравнения их с последующими проектами документации. Представляемые заказчиком комментарии должны быть в виде, позволяющем персоналу разработчиков документации внести предлагаемые изменения в проект документации без дальнейших пояснений.
6 Для больших сложных систем или систем, разрабатываемых одновременно с документацией, может быть необходимо более двух проектов документации и наличие гранок. В этом случае максимальное число проектов (редакций) документации должно быть оговорено между заказчиком и документатором и указано в плане документирования.
7 При проверке проектов документации используют редакционные разметки (знаки, цвета, разметка шрифтов и прочее), Целью редакционных разметок является выделение частей публикации, нуждающихся в уточнении. Тем самым предотвращается необходимость в повторных проверках проектов. Настоятельно реко¬мендуется для внесения редакционной разметки использовать средства автоматизированного сравнения доку¬ментов (при их наличии).
При редакционной разметке рекомендуется:
a) не вносить разметку в распечатку первого проекта (редакции) новой публикации;
b) использовать разметку для показа изменений, вносимых в оригинал проверяемой публикации;
c) во втором проекте использовать разметки с номером 1 для указания изменений, внесенных по ре¬зультатам проверки первой редакции;
d) в третьем проекте использовать разметки с номером 2 аналогично номеру 1;
e) после принятия третьего проекта все разметки в нем должны быть сохранены до проверки гранок публикации.
8.1.4.2 Проверка плана документирования
Данная проверка должна гарантировать, что документация, предусмотренная планом документи-рования, после его выполнения будет удовлетворять целям заказчика. При утверждении плана доку-ментирования заказчик согласовывает все характеристики номенклатуры поставки, предусмотренной планом.

П р и м е ч а н и е — Заказчики должны уделять особое внимание структуре, полноте и практичности документации в соответствии с планом-проспектом ее содержания. План документирования должен быть про¬верен и утвержден (согласован) до начала работ над первым проектом документации. Рекомендации по оценке плана приведены в приложении G.
8.1.4.3 Проверка первой редакции
Первая редакция (проект) должна содержать основную часть документации в соответствии с планом документирования, а также содержание, приложения и словарь (словник, определения). При применении средств автоматического создания указателя каждая его предметная рубрика (индекс) должна ссылаться на конкретные пункты документации. Орфография, пунктуация, стиль и компонов¬ка документации должны соответствовать указанным в плане документирования.
Первый проект документации должен быть проверен заказчиком. Данная проверка предназначена для контроля технической правильности и полноты документации и должна гарантировать соответ¬ствие данного проекта заданиям плана документирования. Также проверяют соответствие орфографии, пунктуации, стиля и компоновки документации требованиям плана документирования.
При утверждении первого проекта заказчик согласовывает техническую правильность, структу¬ру, понятность и полноту документации, исключая предложенные изменения.

П р и м е ч а н и я
1 Перед предъявлением заказчику первый проект должен быть отредактирован по следующим причи¬нам:
a) чтобы проверяющий не отвлекался на корректировку типографских и компоновочных ошибок;
b) чтобы любые технические неточности, внесенные при редактировании, были обнаружены прове¬ряющим.
2 Проект должен быть проверен на соответствие выданным заданиям, указанной аудитории, содержа¬нию и другим характеристикам, согласованным в плане документирования. Перед возвратом первого проекта с комментариями документатору заказчик должен быть уверен, что проект, включая все корректировки, соответствует плану документирования.
8.1.4.4 Проверка второго проекта
Во второй проект документации должны быть включены все изменения, согласованные с заказ¬чиком при проверке первого проекта, а комплектность поставки второго проекта по возможности должна соответствовать номенклатуре поставки, оговоренной в плане документирования.
Данная проверка предназначена для контроля правильности внесения в документацию всех изме-нений, указанных заказчиком на этапе первого проекта.
При утверждении второго проекта заказчик согласовывает все аспекты документации за исклю¬чением физической формы представления документации по данному проекту, которая может не соот¬ветствовать указанной в номенклатуре поставки.

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

8.1.5 Т е с т и р о в а н и е д о к у м е н т а ц и и н а п р а к т и ч н о с т ь
8.1.5.1 Общие положения
В плане документирования должен быть указан требуемый уровень тестирования документации на практичность.
Минимально должно быть проведено одно тестирование на практичность документации, исполь-зуемой для выпускаемой версии программного средства.

П р и м е ч а н и я
1 Тестирование на практичность следует рассматривать как дополнения к проводимым проверкам и анализам документации. Подобное тестирование при разработке должно проводиться на прототипе докумен¬тации, наиболее полно моделирующем ее окончательную версию.
2 При установлении условий данного тестирования должен быть полностью указан стандарт на характе-ристики практичности, по которому проводят измерение. Следует также определить соответствующий(е) ме- тод(ы) измерения и процесс описания результатов замеров.
3 При необходимости в плане документирования следует определить среду тестирования, которая долж¬на полностью соответствовать эксплуатационной среде конечного пользователя.
4 Тестирование на практичность может быть использовано для оценки (измерения) практичности по ГОСТ Р ИСО/МЭК 12119.
8.1.5.2 Планирование
В плане документирования должны быть полностью описаны условия тестирования, включая:
a) этап(ы) жизненного цикла разработки, на котором(ых) должно проводиться тестирование;
b) цели тестирования;
c) используемые показатели (например, время реакции задач);
d) среду тестирования;
e) число и вид привлекаемых пользователей;
f) процесс описания результатов тестирования и рекомендаций по ним;
g) процесс обеспечения реализации рекомендаций по результатам тестирования;
h) процесс доведения результатов тестирования до всего персонала разработчиков документации и заказчика;
i) обязанности персонала разработчиков документации, участвующего в тестировании;
j) процесс определения необходимости последующего тестирования.

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

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

П р и м е ч а н и е — Документатор должен заключить соглашения с субподрядчиками в соответствии с настоящим стандартом.
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 Разрешающая способность типографского или лазерного способа печати
Должна быть определена минимально допустимая разрешающая способность печати (количество точек в 1 дюйме/1 мм).
П р и м е ч а н и е — Минимально рекомендуемой является разрешающая способность 300 точек/дюйм.
8.2.3.1.5 Ширина внутреннего поля
Должно быть определено расстояние от полосы набора до корешка переплета.
8.2.3.1.6. Ширина внешних полей
Должны быть определены расстояния от полосы набора до внешних краев страницы.
8.2.3.1.7 Цвета красок
Должны быть определены цвета красок, используемых при печати.
П р и м е ч а н и е — Если в плане документирования или в договоре указано несколько цветов, любой документатор, не компетентный в области многоцветной печати, должен заранее (до предъявления гранок заказчику) обратиться за консультацией к соответствующим специалистам.
8.2.3.1.8 Цвет, масса и качество бумаги
Должны быть определены цвет, масса и качество (номер) бумаги, используемой для документа¬ции.
П р и м е ч а н и е — Если требуется конкретный номер бумаги, это должно быть указано.
8.2.3.1.9 Разделители
Если в документации применяются разделители, должны быть указаны их цвет, масса и качество. В спецификации стиля должна быть определена информация, печатаемая на разделителях, а также их формат, ориентация и используемый шрифт.
8.2.3.1.10 Метод воспроизведения (тиражирования) и качество
Должен быть указан метод тиражирования документации (печатный, фотокопировальный и т. д.), а также соответствующие ему показатели качества.
8.2.3.1.11 Переплет
Должен быть указан метод переплетения документации.
8.2.3.2 Схемы нумерации
8.2.3.2.1 Нумерация страниц
Должна быть определена схема нумерации страниц.

П р и м е ч а н и я
1 Каждая страница должна иметь индивидуальный номер. Номера страниц должны быть проставлены в порядке их брошюрования.
2 При брошюровке документа с заменяемыми страницами схема нумерации должна учитывать номер текущей главы (раздела) с номером страницы в данной главе (разделе), например «1—1», «1—2» и т. д. (тем самым обеспечивается вставка страниц в документ без перенумерации всех последующих страниц).
3 В случае брошюровки документа без замены страниц используют порядковую номерацию, например «1», «2» и т. д. Иногда для нумерации страниц содержания используют другую схему («i», «ii» и т. д.). Следует избегать схожих методов нумерации страниц вспомогательного (указателя и т. д.) и вводного материалов, так как это может привести к неоднозначности в случае изъятия или вставки страниц.
8.2.3.2.2 Нумерация таблиц и рисунков
Должны быть определены схемы нумерации рисунков и таблиц (при необходимости их нумера¬ции).
П р и м е ч а н и е — Рисунки и таблицы в документе (частях документа) должны иметь индивидуальную нумерацию. Рисунки и таблицы должны нумероваться в порядке их расположения в документе (частях доку¬мента). Может быть использована единая, последовательная нумерация рисунков и таблиц.
8.2.3.3 Использование сносок или концевьх примечаний
Должны быть указаны возможности применения сносок или концевых примечаний.

П р и м е ч а н и е — В документации пользователя программного средства данные элементы обычно не используют; в спецификации стиля следует запретить их применение.
8.2.3.4 Правила пагинации и плотности документа
Должны быть определены правила пагинации (постраничного разбиения, например, чтобы заго¬ловки не проставлялись в конце страницы) и плотности документа (например, регулирование количе¬ства чистых страниц, начальных и концевых висячих строк).
8.2.3.5 Вводные и вспомогательные материалы
Должны быть определены виды вводных и вспомогательных материалов, включая (при необхо¬димости) требования к содержанию и оформлению:
a) титульного листа;
b) информации о гарантиях, авторских правах, компенсациях и торговой марке;
c) содержания;
d) списка рисунков и таблиц;
e) приложений;
f) словаря (глоссария);
g) перечней обозначений и сокращений;
h) указателя.
Должен быть определен порядок расположения данных элементов в документе.

П р и м е ч а н и е — Следует установить требования к содержанию и оформлению вводных и вспомога¬тельных материалов только необходимых видов.
8.2.3.6 Текст основной части документа
8.2.3.6.1 Гарнитуры и кегли шрифтов
Должны быть определены гарнитуры и кегли шрифтов, используемых в основной части доку¬мента.
8.2.3.6.2 Число колонок
Должно быть указано число колонок, используемых при оформлении страниц документа.
П р и м е ч а н и е — Наиболее часто в документации пользователя программного средства используют одноколонное оформление страниц, но может быть также использовано двухколонное оформление.
8.2.3.6.3 Отступы по горизонтали и пробелы по вертикали
Для текста основной части издания должны быть определены отступы (втяжки) слева или справа от края набора основного для издания формата, когда часть строк полосы набирают на более узкий формат со сдвигом влево (правосторонняя втяжка), вправо (левосторонняя), с обеих сторон (двусто¬ронняя), а также пробелы по вертикали (например, межстрочные, межабзацевые).

П р и м е ч а н и я
1 Для языков романской группы в тексте основной части документа следует избегать строк длиной более 65 и менее 30 символов.
2 Для подсчета соответствующей длины строки изначально выбирают строку длиной 5 см и считают количество символов (включая пробелы), содержащихся в десяти строках обычного текста (без разбивки на абзацы) данной длины. Полученное число делят на 50 для определения среднего числа символов на 1 см. Затем принимают решение о необходимом количестве символов в строке (которое должно быть между 30 и 65) и делят его на ранее определенное среднее число символов на 1 см для получения необходимой длины строки в сантиметрах.
8.2.3.6.4 Выравнивание
Должны быть определены параметры выравнивания текста основной части на выбранном языке (например, левостороннее или по ширине).
8.2.3.7 Заголовки
8.2.3.7.1 Количество уровней и наименования заголовков
Должно быть определено количество уровней заголовков, а для каждого уровня задано его обо¬значение или нумерация.
П р и м е ч а н и е — Следует избегать использования более трех уровней заголовков. Трех уровней обычно достаточно.
8.2.3.7.2 Стиль текста заголовков
Должен быть определен стиль текста заголовков для используемых в документации языков (на¬пример, «Стиль основных предложений», «Все буквы заглавные»).
8.2.3.7.3 Гарнитуры, кегли шрифтов и отступы для заголовков каждого уровня
Должны быть определены гарнитуры и кегли шрифтов, отступы по горизонтали и интервалы по вертикали для каждого уровня заголовков.
8.2.3.7.4 Графические элементы, используемые в заголовках
Должны быть определены графические элементы (например, подчеркивание, раскраска, пикто¬граммы), применяемые на каждом уровне заголовков.
8.2.3.8 Верхние и нижние колонтитулы
8.2.3.8.1 Содержание колонтитулов
Должно быть определено содержание заполнения верхних и нижних колонтитулов.
П р и м е ч а н и е — Например, таковыми могут быть номера страниц, проставляемые на полях.
8.2.3.8.2 Гарнитуры, кегли шрифтов и расположение колонтитулов
Должны быть определены гарнитуры и кегли шрифтов, а также горизонтальное и вертикальное расположение верхних и нижних колонтитулов. При двусторонней печати отдельно должно быть опре-делено содержание и оформление верхних и нижних колонтитулов левых и правых страниц.
П р и м е ч а н и е — Например, расположение номеров страниц на страницах каждого типа.
8.2.3.8.3 Используемые графические элементы
Должны быть определены графические элементы (например, подчеркивание, раскраска, пикто¬граммы), применяемые для колонтитула каждого типа.
8.2.3.9 Надписи
8.2.3.9.1 Содержимое
Должно быть определено содержимое надписей.
8.2.3.9.2 Гарнитуры, кегли шрифтов и расположение
Должны быть определены гарнитуры и кегли шрифтов, а также расположение надписей в доку¬менте.
8.2.3.10 Таблицы
8.2.3.10.1 Правила оформления
Должны быть определены правила оформления таблиц, например головки таблиц следует повто¬рять при переходе на другую страницу.
8.2.3.10.2 Гарнитуры и минимальные кегли шрифтов
Должны быть определены гарнитуры и минимальные кегли шрифтов, используемых в таблицах.
8.2.3.11 Отчеты (сообщения)
8.2.3.11.1. Общие положения
Отчеты (сообщения) являются результатами работы прикладных программных средств, выдавае¬мые в печатном или экранном виде. Образцы отчетов обычно включают в документацию пользователя программного средства.
8.2.3.11.2 Содержание
Могут быть установлены правила оформления и содержания отчетов.
П р и м е ч а н и е — Отчеты лучше понимаются, когда на каждом их поле распечатки экранов отражены реальные данные. В отчетах также должны быть использованы функциональные данные.
8.2.3.11.3 Гарнитуры и минимальные кегли шрифтов
Должны быть определены гарнитуры и минимальные кегли шрифтов, используемые в отчетах.
8.2.3.11.4 Использование горизонтальной компоновки и страниц-раскладок
Должны быть определены правила по использованию горизонтальной компоновки (то есть аль¬бомных форматов) для очень широких или длинных отчетов. Должны быть также установлены правила использования в отчетах страниц-раскладок и страниц-разверток.
8.2.3.12 Распечатки экранов
8.2.3.12.1 Содержание
Должны быть установлены общие правила содержания распечаток экранов.
П р и м е ч а н и е — Распечатки экранов лучше понимаются, когда на каждой из них отражены реальные данные. В распечатках также должны быть использованы функциональные данные.
8.2.3.12.2 Оформление (компоновка)
Должны быть установлены общие правила оформления (компоновки) распечаток экранов.
8.2.3.12.3 Оформление частичных распечаток экранов
Должны быть установлены (при необходимости) правила оформления частичных (неполных) распечаток экранов.
8.2.3.13 Рисунки
8.2.3.13.1 Минимальная толщина линий, гарнитуры и кегли шрифтов
Должны быть установлены, используемые в рисунках гарнитуры и кегли шрифтов, а также минимальная толщина линий.
8.2.3.13.2 Расположение
Должны быть установлены правила расположения (ориентации) рисунков.
8.2.3.14 Уведомления и предостережения
8.2.3.14.1 Стиль текста
Должен быть определен стиль текста уведомлений и предостережений для используемых в доку-ментации языков (например, «Стиль основных предложений», «Все буквы заглавные»).
8.2.3.14.2 Гарнитуры, кегли шрифтов и отступы
Должны быть определены гарнитуры и кегли шрифтов, отступы по горизонтали и интервалы по вертикали для уведомлений и предостережений.
8.2.3.14.3 Графические элементы, используемые в заголовках
Должны быть определены графические элементы (например, подчеркивание, раскраска, пикто¬граммы), используемые в уведомлениях и предостережениях.

8.2.4 Э л е к т р о н н а я д о к у м е н т а ц и я
8.2.4.1 Типы справочной информации
В спецификации стиля документации могут быть указаны один или несколько из следующих типов справочной информации:
a) контекстная справка (context help) — информация о текущем поле, в котором находится курсор или высвечена программа, включая ее необходимое или целевое (предметное) содержание, ее назначение и потенциальное влияние на работу программного средства;
b) расширенная справка (extended help) — информация о текущем экране или окне, включая ее назначение и требуемый режим использования;
c) справка о клавишах (keys help) — информация о применении клавиатуры, функциональном назначении клавиш и их перенаименовании (обозначении);
d) справка о справках (help to help) — информация об использовании справочной системы в целом;
e) справка о сообщении (message help) — информация о том, что пользователь должен или может сделать в ответ на конкретные системные сообщения, например сообщения об ошибках;
f) терминологическая справка (reference phrase help) — определения конкретных элементов, связей с конкретной тематикой и расшифровка обозначений и сокращений;
g) понятийная справка (intelligent help) — справочная информация, выдаваемая системой для предупреждения пользователя об ошибках. Может быть структурирована, чтобы первоначально пользо¬ватель получал краткое справочное сообщение, а при повторении той же ошибки — более подробное сообщение, и наоборот, пользователь может получить развернутое сообщение при первой ошибке и краткое — при ее повторении.
8.2.4.2 Типы диалоговой (оперативной) документации
В спецификации стиля электронной документации могут быть указаны один или несколько из следующих типов диалоговой документации:
a) руководства или рекомендации пользователя (user guide or reference) — описывают процедуры по применению продукта;
b) командные справки (command reference) — определяют синтаксис, результаты и целевое назна¬чение каждой команды (только для команд управления системой);
c) рекомендации по сообщению (message reference) — определяют, что пользователь должен или может сделать в ответ на конкретные системные сообщения, например сообщения об ошибках;
d) административная информация (administration information) — информация о конфигурации и защите системы, а при необходимости — о ее инсталляции, предназначенная для администратора системы.
8.2.4.3 Оформление
8.2.4.3.1 Общее положение
Оформление (компоновка) информации в системах справочной и диалоговой (оперативной) документации во многом может определяться возможностями инструментальных средств, используе¬мых при их создании.
8.2.4.3.2 Сопутствующие материалы
Должны быть установлены правила размещения материалов, связанных с электронной докумен¬тацией, и их местоположение.
8.2.4.3.3 Подсветка и использование цвета
Должны быть установлены правила использования в электронной документации подсветок выде-ляемых элементов и использование цветового оформления.

П р и м е ч а н и я
1 Использование подсветок и цветов для выделения элементов документации должно быть миниминизи- ровано, особенно в случае возможной путаницы между выделенным текстом и гипертекстовыми связями.
2 Цвета следует использовать осторожно, особенно при отсутствии уверенности в том, что тот же цвет не используется для уведомления о более важной информации. Это особенно важно при наличии у пользова¬телей возможностей выбора различного цветового оформления экранов.
3 Для четкого выделения элементов и во избежание возникновения при этом проблем по возможности следует основные цвета (красный, зеленый и синий) использовать на фоне белого или черного.
4 Различные яркие цвета не следует использовать последовательно, так как это может привести к воз-никновению на экране трехмерных эффектов.
5 Обычно некоторые цвета имеют определенные смысловые значения (например, красный — «стой» или «опасно», зеленый — «продолжить» или «безопасно») и могут быть выбраны соответственно этому значе¬нию. Данный тип цветосочетания следует использовать осторожно, если пользователи могут выбирать различ¬ные цветовые оформления экранов.
6 Колористика экранов дисплеев является сложным вопросом и часто связана с недостаточной проект¬ной проработкой. Документаторам в этом случае следует обращаться за помощью к соответствующим специ¬алистам.
8.2.4.3.4 Оформление диалоговой документации и справочного текста
Должны быть установлены правила оформления соответствующих текстов.
8.2.4.3.5 Заголовки
Должны быть установлены правила оформления соответствующих заголовков.
8.2.4.3.6 Текст основной части
Для текста основной части электронной документации должны быть определены следующие элементы:
a) выравнивание (для соответствующих языков);
b) отступы и интервалы.
П р и м е ч а н и е — Для языков романской группы следует избегать строк длиной более 65 и менее 30 символов. Интервал между строками следует устанавливать не менее двух пикселей или 15 % от высоты симво¬ла, независимо от его величины. Это не распространяется на знаки ударения или выносные элементы строч¬ных символов;
c) минимальная высота символа.
П р и м е ч а н и е — Для языков романской группы высота символов должна быть не менее 16 и не более 45 угловых минут. Предпочтительной высотой символа являются 20—22 угловые минуты. Угловые минуты ис-пользуются в качестве показателя высоты символа на видеодисплее; данный показатель отражает охват симво¬ла глазом. Он зависит не только от фактической высоты символа на экране, но также от нормального расстояния до экрана. В таблице 1 показано отношение между высотой символа в угловых минутах и миллимет¬рах на расстоянии в 1 м. Например, на более коротком расстоянии высота пропорционально уменьшается по сравнению с заданной в таблице. В таблице для сравнения также показано соответствующее число отображае¬мых точек для гарнитуры «Times Roman».

Т а б л и ц а 1 — Угол обзора и число точек

Угол обзора, угловые минуты	Высота, мм	Приблизительное число точек
10	2,9	12
15	4,4	18
20	5,8	24
25	7,3	30
30	8,8	36
35	10,2	42
40	11,6	48
45	13,1	54
50	14,6

8.2.4.3.1 Навигация

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

П р и м е ч а н и я

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

2 Должны быть выработаны и применены правила структурирования документа. Например, количество связей в каждой информационной цепочке должно быть ограничено числом X Значение Xдолжно быть таким, чтобы пользователи имели соответствующие возможности для возврата к содержанию или перехода к другим структурным элементам документа. Уровни заголовков также могут быть взаимоувязаны с уровнями сложности документа (например, «В заголовках первого уровня представляется только общая информация»).

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

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

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

8.2.4.3.2 Использование клавиатуры

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

П р и м е ч а н и я

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

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

3 Применение специальной функциональной клавиши в документации должно быть соотнесено с использованием функциональных клавиш в самом программном приложении.

Перекрестные ссылки с ГОСТ Р ИСО/МЭК 12207

Настоящий стандарт соответствует ГОСТ Р ИСО/МЭК 12207 в части реализации его подраздела 6.1 по отношению к документации пользователя (см. таблицу А.1).

Т а б л и ц а А.1 — Перекрестные ссылки с ГОСТ Р ИСО/МЭК 12207

Пункты ГОСТ Р ИСО/МЭК 12207	Пункты настоящего стандарта
6.1.1.1	8.1.3 План документирования
6.1.2.1	8.2 Содержание спецификации стиля
6.1.2.2	8.1.2 Представление исходных материалов
6.1.2.3	8.1.4 Проверка (анализ)
6.1.3.1	8.2 Содержание спецификации стиля. 8.1.3 План документирования
6.1.3.2	8.1.3.3 Проверка плана документирования
6.1.4.1	8.1.7 Контроль изменений и сопровождение документа

ПРИЛОЖЕНИЕ В (справочное)

Использование настоящего стандарта в договоре
В.1 Общие положения
В настоящем стандарте имеются разделы, требования которых необходимо пояснить применительно к конкретному договору или другим ссылочным документам (например, международным). В свою очередь, план документирования также нуждается в пояснении. В договоре должны быть даны ответы на следующие вопросы:
a) откуда поступает информация о изучении аудитории? (Ответ рекомендуемый);
b) необходимо ли готовить более двух проектов комплекта документации и одного комплекта гранок? (При необходимости, в настоящем стандарте по умолчанию предусмотрены два проекта комплектов доку¬ментации и один комплект гранок);
c) кто представляет исходные материалы? (Обычно это очевидно, но для проектов со сложными взаи-мосвязями между вовлеченными сторонами нуждается в уточнении);
d) какие уровни конфиденциальности или секретности необходимо использовать для материалов, пре-доставляемых заказчиком документатору?
e) имеется ли стандарт на оформление бумажной документации? (Это не обязательно; по умолчанию может быть использована спецификация стиля документации, установленная в настоящем стандарте; затем в плане документирования может быть оговорено количество проектов документации и т. д.).
В.2 Образец раздела договора
В соответствии с настоящим стандартом образец раздела договора может быть представлен в следующем
виде.

П р и м е р
Раздел 123 Документация
Вся документация пользователя должна соответствовать ГОСТ Р ИСО/МЭК 15910.
В комплект документации не следует включать диалоговую документацию и справочные тексты. Вся информация об изучении аудитории и другие исходные материалы должны представляться заказчиком.
Должно быть проведено одно тестирование на практичность при поставке первого модуля программно¬го средства, которое должно предусматривать проверки всех функциональных возможностей данного модуля в интересах пяти различных типовых пользователей.
В.3 Практическое применение настоящего стандарта
Необходима адаптация настоящего стандарта в интересах потребителей и пользователей в целях его практического применения.
Практическое применение настоящего стандарта обычно заключается в исключении и добавлении ряда разделов, что должно быть оговорено соответствующим соглашением (как правило, в договоре, но возможно и в плане документирования).
Практическое применение настоящего стандарта следует проводить тщательно, с учетом его общей структуры.

ПРИЛОЖЕНИЕ С (справочное)

Образец плана документирования. Документация пользователя для системы АВС — административного управления магнитными лентами
С.1 Введение
В настоящем плане описана стратегия разработки документации пользователя для системы АВС, пред-ставляемой в виде комплекта документации XYZ. Определена область применения проекта, номенклатура поставки документации и ресурсы, необходимые для ее создания.
Данная стратегия предусматривает создание твердых копий документации и диалоговой документации в виде справочных текстов.
В случае изменения данной стратегии следует пересмотреть план документирования.
С.2 Область применения и ограничения
В комплекте документации не предусмотрены инструкции по применению операционной системы, на которой прогоняется система АВС. Однако для читателя должны быть указаны ссылки на соответствующие руководства по данному вопросу.
Инсталляция, ввод в действие и управление документацией системы АВС уже реализованы и не рассмат-риваются в настоящем проекте.
С.3 Оформление и стиль описания
По умолчанию следует использовать оформление и стиль описания, указанные в ГОСТ Р ИСО/МЭК 15910. Образец страницы приложен к плану документирования.

Т а б л и ц а С.1 — Руководство по стилю

Элемент	Значение
Содержание справочного текста	Должен быть описан только контекст справки
Содержание диалоговой документации	Отсутствует
Сопутствующие материалы	Справочный текст для каждого объекта должен быть представлен на одном экране
Засветки и использование цветов	В справочном тексте не следует использовать цвета и другие засветки
Оформление диалоговой документации и справочного текста	Должен быть использован одноколонный формат

Окончание таблицы С.1

Элемент	Значение
Оформление заголовков диалоговой документации и справочного текста	Вверху каждой страницы справочного текста должен быть проставлен заголовок первого уровня: кегль 14 п, гарнитура Times Roman
Оформление основной части документа	Текст должен быть выровнен по левому краю и набран одним шрифтом
Правила навигации	В соответствии со справочным механизмом системы АВС
Использование клавиатуры	В соответствии со стандартами на систему АВС

С.4 Аудитория

В аудиторию пользователей данной системы входят операторы компьютеров, обладающие минимальны¬ми техническими знаниями. Минимальное образование операторов должно соответствовать 12-летнему сред¬нему (школьному) образованию.
Аудитория не охватывает безграмотных пользователей; все пользователи должны обладать хорошими навыками чтения.
Пользователи должны иметь однолетний (двухлетний) опыт работы в качестве операторов вычисли¬тельного центра, включая навыки по эксплуатационным процедурам запуска, остановки, резервирования и сохранения систем, а также загрузки и разгрузки магнитных лент. В их обязанности также должен входить контроль диагностических сообщений от системы и реакция на них.
Предполагается, что пользователи:
a) понимают общие процедуры управления магнитными лентами;
b) обладают адекватным восприятием соответствующих команд операционной системы;
c) не имеют навыков работы с магнитными лентами в системе АВС.
С.5 Проект содержания документации
Содержание включает в себя следующее:
a) введение — концепция АВС и ее связь с системой (пять страниц);
b) обзор — общие функции системы АВС (три страницы);
c) установка ленты (пять страниц);
d) снятие ленты (пять страниц);
e) проблемы — руководство по определению дефектов, включая системные сообщения (четыре страницы);
f) словарь терминов и определений (одна страница);
g) указатель (одна страница).
Всего 24 страницы.
С.6 Номенклатура поставки
По окончании проекта должны быть поставлены следующие объекты:
a) 500 переплетенных копий руководства;
b) электронная копия всей документации на дискетах емкостью 1,44 Мбайт, диаметром 3,5 дюйма в формате DEF 3.0 (пригодная для распечатки документации на принтере);
c) электронная копия справочного текста.
С.7 Авторские права
Авторские права на все материалы принадлежат организации XYZ.
С.8 Транспортирование
Особых условий по транспортированию продукции не требуется.
С.9 Процесс разработки и контроль
При создании руководств пользователя системы АВС должны использоваться процедуры разработки и контроля, установленные в Руководстве по качеству организации XYZ.
С.10 Тиражирование
При производстве руководств пользователя системы АВС следует использовать типографскую систему DEF (версия 3.0). Графические материалы следует разрабатывать с использованием графического пакета JKL.
Виды экранов дисплея для системы АВС следует собрать в электронном виде, а их копии — внести в окончательный документ.
Содержание и указатель должны быть подготовлены и выпущены на системе DEF.
Копии фотошаблонов должны быть отпечатаны на лазерном принтере с плотностью печати 300 точек на дюйм; за отдельную плату они могут быть распечатаны на лазерном принтере высокого качества с плотно¬стью печати 1275 точек на дюйм.
Каждое руководство должно быть выполнено в формате А4 с двусторонней печатью и сброшюровано так, чтобы была возможность заменять листы.
Переплет должен быть формата А4 и скреплен кольцами диаметром 25 мм. На обложке должны быть приведены распечатки экранов системы АВС.
Бумага для руководств должна быть матовой и иметь плотность 103 г/см2.
Справочные тексты должны быть разработаны с использованием макетирования в системе DEF.
С.11 Проектанты
Состав коллектива разработчиков и их обязанности приведены в таблице С.2.

Т а б л и ц а С.2 — Проектанты

Фамилия, имя	Роль	Обязанность
О’Брайен П.	Автор	Изучение плана и написание руководств
Коста А.	Редактор	Редактирование руководств
Ричардс Р.	Нормоконтролер	Проверка технического содержания руководств
Джонс Е.	Технический аудитор	Проведение технических проверок и выдача рекомендаций
Вонг С.	Разработчик	Набор текста и подготовка графических материалов
Келли А.	Ответственный за качество	Управление качеством
Даунс М.	Ответственный за тестирование	Тестирование готового руководства при определенных условиях и подготовка отчета о результатах тестирования

С.12 Ресурсы
Информацию, необходимую для разработки руководств, следует выбирать из проектной документации на систему АВС, получать от разработчиков программных средств и отбирать по результатам опытной эксплу¬атации данной системы.
Разработчикам документации необходимы следующие ресурсы:
a) копии функциональной проектной документации на систему АВС;
b) доступ к системе АВС;
c) доступ к разработчикам программного обеспечения системы АВС.
С.13 Тестирование на практичность
После корректировки второго проекта документации по замечаниям заказчика должно быть проведено тестирование на практичность руководства пользователя и справочных текстов для системы АВС.
Целью тестирования является оценка степени, в которой язык, содержание и оформление руководства пользователя и справочных текстов для системы АВС облегчают пользователям практическое применение программных средств данной системы.
Тестирование должно проводиться в машинном зале с использованием бета-версии тестов для АВС; в тестировании должно участвовать по одному представителю от разработчиков программных средств и разра-ботчиков документации (далее — представители).
Тестирование должно проводиться с привлечением четырех типовых пользователей, перечисленных в С.4, выбранных произвольно из персонала ночной смены, эксплуатирующего систему. Каждому из них долж¬ны быть даны копии руководства пользователя и справочных текстов для системы АВС с просьбой выполнить ряд действий (перечисленных в плане тестирования).
Представители записывают время выполнения каждого действия, замечания пользователя и процессы, выполняемые пользователями при реализации каждого действия.
При превышении любым пользователем времени выполнения действия, указанного в плане тестирова¬ния, или неправильном выполнении данного действия представители записывают соответствующие замеча¬ния пользователя о причинах возникшей проблемы.
Эти замечания представляются на совещании по рассмотрению документации и в качестве изменений в проект документации. На совещании определяют целесообразность проведения повторного тестирования.
С.14 График работ
График работ показан в таблице С.3.
Т а б л и ц а С.3 — График работ

Этап	Срок	Отношения
Представление первого проекта	01.01.99	План документирования утвержден 15.12.98
Представление второго проекта	15.02.99	Три недели на проверку первого проекта
Тестирование на практичность	15.03.99
Представления справочных текстов	15.04.99	Тестирование на практичность
Представление гранок	15.04.99	Тестирование на практичность; две недели на проверку второго проекта
Подготовка фотошаблонов	30.04.99	Тестирование на практичность
Распечатка и брошюровка	15.05.99	Наличие переплетенных томов

ПРИЛОЖЕНИЕ D (справочное)

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

Рисунок D.1 — Иерархия аудиторий

В ряде случаев следует выбирать аудиторию, исходя из опытности пользователя данной аудитории по использованию системы. Например, аудитории могут быть определены как «Неопытные пользователи» или «Опытные пользователи».
После определения перечня аудиторий для конкретной системы на следующем этапе следует опреде¬лить задания (tasks), выполняемые каждой аудиторией. Часто данные задания представляют в виде иерархичес¬кой структуры (см. рисунок D.2).

Рисунок D.2 — Иерархия заданий

На следующем этапе для определенной аудитории в рамках выданных ей заданий определяют перечень ее потребностей в информации (information needs). На основе данного перечня определяют содержание конкретного документа, как показано на рисунке 3.

Рисунок D.3 — Информационные потребности

На данном этапе (но не ранее) следует определить вид (тип) конкретного документа и машинный носитель, на котором он поставляется.

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

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

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

Рисунок D.4 — Общая структура процесса проектирования документирования Более подробное описание процесса проектирования документации приведено в BS 7649—93 [2].

Рекомендации по написанию на английском языке документации, подлежащей последующему переводу

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

Е.2 Терминология
В части терминологии, используемой в документах, необходимо руководствоваться следующими прави¬лами:
a) применять общие и нетехнические термины в соответствии с их определениями, установленными в общих словарях;
b) создавать глоссарии (словники), содержащие:
1) определения всех специфических и неизвестных терминов,
2) виды и определения всех обозначений и сокращений,
3) толкования непривычного использования слов, применение имен существительных в качестве наречий,
4) библиографию специализированных словарей и стандартов;
c) специальная терминология должна быть основана на национальных или международных терминоло-гических стандартах, общепризнанных словарях или согласованных глоссариях;
d) каждое сокращение должно быть расшифровано при первом его появлении в тексте основной части документа;
e) каждый термин должен одинаково трактоваться в документе, диалоговой информации и системной библиотеке;
f) составные выражения (например, «ввод данных [data input]») должны иметь одно смысловое значение во всей документации;
g) составные выражения не должны содержать более трех слов;
h) одно и то же слово не должно использоваться для различных частей речи;
i) все специфические и специальные термины должны использоваться в соответствующем контексте; j) термины, вводимые вне соответствующего контекста, например наименования клавиш или коман¬ды, должны быть определены в глоссарии;
k) следует избегать использования термина «биллион (billion)».
П р и м е ч а н и е — Американский биллион (109) не совпадает с английским биллионом (1012);
1) следует избегать использования термина «перевод (translation)», например при ссылке на перевод в формат файла, в смысловом значении, отличном от перевода с одного языка на другой. Вместо этого следует применять термин «преобразование (со^еЛю^)».
Е.3 Стиль перевода

Е.3.1 О б о з н а ч е н и я
Следует использовать только общепринятые обозначения, которые должны быть расшифрованы в спис¬ке обозначений. Не должны применяться следующие обозначения:
a) американский символ «#» для фунта;
b) приподнятая точка (•) для операции умножения. Е.3.2 Н е о д н о з н а ч н о т р а к т у е м ы е с л о в а
Авторы документов должны избегать использования следующих неоднозначно трактуемых слов:
a) who (кто), that (который), which (какой);
b) only (только), merely (приблизительно), just (едва), mainly (в основном), simply (просто);
c) while (пока);
d) so (таким образом);
e) as (как);
f) can (иметь возможность), may (мочь);
g) since (так как);
h) when (когда), if (если);
i) alternate (дополнительный), alternative (альтернативный).

Е.3.3 С и н т а к с и с
Должны быть учтены следующие вопросы синтаксиса:
a) предложения не должны быть слишком длинными;
b) следует избегать построения предложений, описывающих ряд положений, разделяемых чрезмерным количеством запятых;
c) пункты, содержащие определенные ограничения, и пункты без ограничений должны быть представ¬лены раздельно.

Е.3.4 П у н к т у а ц и я
Там, где могут быть использованы скобки или точка с запятой, не следует применять тире.
Е.4 Физические факторы
Необходимо учитывать следующие физические факторы:
a) сокращения нецелесообразно использовать только для экономии места;
b) предусмотреть необходимые места для простановки соответствующих значений, например цены;
c) следует использовать стандартные графические инструментальные средства (пакеты) и избегать при-менения вклеек;
d) избегать внесения поясняющего текста в рисунки;
e) следует использовать графические символы, имеющие общепринятое смысловое значение;
f) по возможности вместо словесного пояснения использовать графические изображения.

Е.5 Диалоговая информация
Применительно к диалоговой информации необходимо учитывать следующие положения:
a) при наличии обратной связи с разработчиками программных средств следует обеспечить выделение диалоговой информации (текстов и сообщений) из логики программы;
b) каждый блок текста или сообщение должны иметь индивидуальное идентификационное обозначение с указанием соответствующей классификационной группы данного текста или сообщения;
c) конкретное программное средство не должно ориентироваться на длину, формат или расположение незащищенных экранных полей ввода—вывода (input and output fields);
d) для каждого понятия следует использовать отдельное сообщение. Сообщения не должны быть наду-манными;
e) переменные в сообщении должны содержать только непереводимую информацию, например ключе¬вые слова и коды возврата;
f) из предложений не следует исключать предлоги в целях экономии места.

Е.6 Культурные факторы
Применительно к культурным факторам необходимо учитывать следующие положения:
a) иллюстративные материалы (например, лица, животные и звуки речи) должны быть независимыми от национальных культурных особенностей;
b) следует избегать использования примеров, связанных со специфическими национальными традиция¬ми или особенностями (например, праздниками, банковским делом, зарплатой, спортом и т. д.);
c) в тексте и иллюстрациях следует избегать использования идиоматических выражений, присущих наци-ональному языку документатора;
d) следует избегать использования юмористических выражений, особенно каламбуров.
e) следует осторожно использовать иронические выражения;
f) необходимо избегать использования сленговых, жаргонных и простонародных выражений;
g) не должны использоваться упоминания первых лиц государства;
h) не следует выражать даты только в числовом виде. Месяц всегда должен быть написан полностью (например, 28 июля 1991);
i) обычно следует использовать двумерные представления, если международные соглашения не требу¬ют иного (например, для автошин, водопроводов, гвоздей и фотопленки);
j) когда метрические величины располагаются вместе с величинами в других системах измерения, из контекста должно быть понятно, какая из величин относится к соответствующей системе измерений.
Оценка проекта

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

F.2 Поминутный и почасовой методы
Данные методы предусматривают около 3 ч для написания страницы текста, пригодного для публикации. Время, необходимое для создания графических материалов, определяется их сложностью и количеством чер-новиков, необходимых для создания соответствующего оригинала.
По общей оценке требуется от 3 до 5 ч для создания и корректировки типового графического материала, используемого в программной документации (исключая экранные распечатки).
В начале проекта трудно оценить общий постраничный объем создаваемой документации. Если для завер-шения проекта требуется более 2 мес, подсчет страниц должен быть проведен по истечении первого месяца.
Для очень больших проектов номенклатура поставки должна быть разделена на части, поддающиеся управлению. При этом оценка сроков завершения проекта в целом может быть дана только в количестве месяцев, а детально может быть оценена лишь первая часть работы. При использовании данного метода доку¬ментатор и заказчик должны сверить свои оценки сроков завершения проекта.
В таблице F.1 приведены сроки реализации «типового» (гипотетического) проекта. При этом предпо¬лагается, что автор готовит материалы непосредственно на персональном компьютере, и для их выпуска используют портативные издательские системы.

Т а б л и ц а F.1 — Ориентировочные сроки

Этап	Срок
Определение номенклатуры поставки	16 ч на проект
Исследование содержания документации	24 ч на проект
Написание плана документирования	48 ч на проект
Проектирование структуры документа и правил оформления его страниц	8 ч на том
Написание первой редакции (документации)	1 ч на страницу
Разработка графических материалов	5 ч на материал
Объединение текстовых и графических материалов	30 мин на страницу
Проверка первой редакции (эксперт)	30 мин на страницу
Корректировка первой редакции и графики	30 мин на страницу
Внесение замечаний пользователя	30 мин на страницу
Грамматическое редактирование	15 мин на страницу
Подготовка второй редакции (документации)	15 мин на страницу
Проверка второй редакции (эксперт)	15 мин на страницу
Окончательная корректировка документации	10 мин на страницу
Нормоконтроль документации	15 мин на страницу
Изготовление фотошаблонов	3 сут
Печать и переплетение оригиналов	5 сут
Печать и брошюровка копий	10 сут
Рассылка	1 су

F.3 Метод нисходящего проектирования

F.3.1 О б щ и е п о л о ж е н и я
Данный метод основан на предположении, что число страниц в публикации(ях) может быть оценено достаточно просто с использованием следующих допущений:
a)    автор может за месяц подготовить 22 страницы нового текста;
b)    автор может за месяц подготовить 44 страницы текста с изменениями.
Например, объем публикации оценен в 150 страниц. Поскольку это новая публикация, получаем: 150/22 = 7 чел./мес. В эти 7 мес входят: планирование публикации, ее написание, редактирование и проверка двух редакций, а также подготовка фотошаблонов. F.3.2 П р о п о р ц и и
Продолжительность 7 чел./мес распределена в следующих пропорциональных отношениях:
a)    15 % — планирование (в данном примере — четыре недели);
b)    50 % — написание первой редакции (14 недель);
c)    25 % — написание второй редакции (семь недель);
d)    10 % — подготовка фотошаблонов (три недели). F.3.3 П л а н и р о в а н и е
Период планирования охватывает:
a)    исследования и подготовку плана;
b)    изучение и проверку плана;
c)    корректировку плана по результатам проверки. F.3.4 П е р в а я р е д а к ц и я
Период первой редакции охватывает:
подготовку содержания (плана-проспекта) документации;
изучение и проверку содержания (плана-проспекта);
подготовку пробного куска текста для редактора;
редактирование пробного куска текста и его переписывание по замечаниям редактора;
написание всей первой редакции документации;
редактирование всей первой редакции документации;
переработку отредактированной документации;
изучение и проверку переработанной документации.
Иллюстративные материалы готовят одновременно с текстом первой редакции. F.3.5 В т о р а я р е д а к ц и я Период второй редакции охватывает:
a)    внесение в документацию всех изменений, предложенных по результатам проверки первой редакции;
b)    повторное (второе) редактирование второй редакции документации;
c)    переработку отредактированной документации;
d)    изучение и проверку переработанной документации. F.3.6 П р и н я т а я р е д а к ц и я
Редакцией для фотонабора является принятая редакция документирования. Ее подготовка охватывает:
a)    внесение в документацию всех изменений, предложенных по результатам проверки второй редакции;
b)    проверку правильности внесения данных изменений;
c)    удаление всех редакционных разметок;
d)    изготовление фотошаблонов;
e)    отправку фотошаблонов в печать (в типографию).
Обычно экспертам (нормоконтролерам) требуется от одной до двух недель для изучения и подготовки замечаний, а сама проверка занимает от одного до нескольких дней.
Метод нисходящего проектирования может быть использован для существующих публикаций. Напри¬мер, книга объемом 100 страниц может быть переработана так, что половина ее изменяется и добавляется 10 % новых материалов. Используя вышепринятые допущения, получаем: 50/44 = 1,13 чел./мес для существую¬щего материала плюс 10/22 = 0,45 чел./мес для внесения нового материала.
Когда сроки, необходимые для создания документации, превышают допустимые, для выполнения зада¬ния следует привлекать несколько авторов. Так же следует поступать при подготовке нескольких документов для одного программного средства.
Оценка плана документирования
Использование настоящего стандарта во взаимоотношениях между заказчиком и документатором спо-собствует созданию качественной документации в частности потому, что между ними согласовывается план документирования. Этим достигается двойной эффект: во-первых, документатор учитывает все аспекты доку-ментации, оговоренные в плане; во-вторых, заказчик и документатор согласуют метод документирования, определенный в плане, еще до начала работы.
Заказчик должен установить наличие в плане документирования следующих элементов:
a)    соответствующих определений всех аудиторий. Формулировка вида «Руководство предназначено для аудитории, охватывающей пользователей программного средства» неполна (см. приложение D). В определение аудитории должны быть включены все лица, могущие использовать данное программное средство (включая лиц, которые могут только просматривать отчеты или сообщения от данного средства);
b)    содержания (планов-проспектов) документации с оценкой их постраничного объема;
c)    определения числа печатных копий и методов печати (тиражирования) и брошюровки документации;
d)    однозначного определения собственника авторских прав на документацию;
e)    установление методов подготовки документации. Большинство технических документов может быть создано при помощи компьютера;
f)    достаточных сроков для проверки заказчиком редакций документации. Любые отсрочки при возврате документатору проверенных редакций могут привести к срыву сроков поставки документации;
g)    от организации-заказчика может потребоваться обеспечение документатора соответствующими ресур-сами (доступом к ее персоналу, оборудованием и т. д.), при отсутствии которых работы могут быть сорваны.
В целом план документирования должен учитывать все специфические обстоятельства, относящиеся к организации-заказчику и пользователям. Крайне маловероятна возможность использования плана документи-рования, разработанного в рамках одного проекта, для другого.

ПРИЛОЖЕНИЕ Н (справочное)

Образец спецификации стиля

Н.1 Общие положения
Представленный образец спецификации стиля документации соответствует требованиям 8.2 и по умол¬чанию может быть использован в плане документирования.
П р и м е ч а н и е — Перед окончательным принятием данной спецификации полезно создать на ее основе модель документа.

Н.2 Элементы стиля
В таблице Н.1 приведены элементы стиля и их рекомендуемые значения по умолчанию.

Т а б л и ц а Н.1 — Элементы стиля и их значения

Элемент	Значение
Язык	Английский
Орфографический словарь	Словарь Маквайра
Руководство по грамматике и использованию стиля	«Руководство по стилю для авторов, редакторов и издателей» Австралийское государственное издательство

Продолжение таблицы Н. 1

Элемент	Значение
Формат бумаги	А4
Ориентация	Книжная (вертикальная)
Вид печати	Двусторонняя
Разрешающая способность типографской или лазерной печати	Минимум 300 точек/дюйм
Ширина внутреннего поля	10 мм/2,4 цицеро*
Ширина внешнего поля	10 мм/2,4 цицеро*
Цвет краски	Черный
Цвет, масса и вид бумаги	Белая, 80 г/см², матовая
Разделители	Нет
Переплет	Пластиковый комбинированный, с прозрачной верхней и черной нижней обложками, плотностью 200—260 г/см²
Метод воспроизведения и качество	Все материалы должны быть пригодными к фотокопированию и не иметь помарок и обесцвечиваний
Схема нумерации страниц	Страницы нумеруют в формате 1, 2, 3 и т. д., начиная с первой после обложки
Нумерация таблиц и рисунков	Рисунки нумеруют в формате «Рисунок 1», «Рисунок 2» и т. д., в порядке их появления в тексте документа. Таблицы нумеруют в формате «Таблица 1», «Таблица 2» и т. д., в порядке их появления в тексте документа
Число колонок	Одна
Сноски или концевые примечания	Не используют
Правила пагинации	Заголовки не должны попадать в конец страницы. Таблицы объемом менее страницы должны размещаться на одной странице. Каждый заголовок первого уровня должен располагаться вверху правой страницы
Правила плотности документа	Взаимосвязанные материалы следует размещать на одной странице или на ее обороте. Следует по возможности избегать использования подчеркивания, больших кусков, набранных жирным шрифтом, и текстов, целиком набранных заглавными буквами. Материалы должны занимать от 40 % до 60 % общего объема страницы
Вводные и вспомогательные материалы: – титульный лист	На титульном листе должно быть указано наименование продукции, ее версия, дата выпуска документа и название данного тома

Продолжение таблицы Н.1

Элемент	Значение
информация о гарантиях, авторских правах и торговой марке содержание список рисунков и таблиц приложения глоссарий перечни обозначений и сокращений указатель порядок	Не приводится В содержании должны быть приведены заголовки всех частей, глав и разделов с указанием номеров страниц Не приводится Не предусмотрены В глоссарии должен быть определен любой термин, неизвестный аудитории пользователей документа, в терминах, знакомых данной аудитории Следует указать все встречающиеся в тексте обозначения и сокращения. Если данные элементы не являются очевидными по смыслу, они должны быть пояснены соответствующим текстом В соответствии с Н.3 Располагаются в порядке их перечисления в настоящей таблице, основная часть документа располагается между содержанием и глоссарием
Гарнитуры шрифтов и кегли текста основной части документа	Times Roman, 12 п
Отступы по горизонтали и пробелы по вертикали в тексте основной части	Текст основной части должен иметь общий отступ на 2 п и левосторонний отступ на 30 мм/7 цицеро. Между абзацами должен быть вертикальный пробел в одну строку
Выравнивание текста основной части	Текст основной части должен быть выровнен по левой стороне с неровностями по правому краю
Количество уровней и наименования заголовков	Четыре; заголовки части, главы, раздела и подраздела
Стиль текста заголовков	Все заголовки должны быть изложены в повествовательном стиле с заглавной буквы и без точки в конце
Гарнитуры шрифтов, кегли и отступы для каждого уровня заголовков	Все заголовки оформляют шрифтом Times Roman следующими кеглями: заголовок части — 36 п, главы — 24 п, раздела — 18 п, подраздела — 14 п. Заголовки должны быть выровнены по левому краю. Вверху каждого заголовка должен быть пробел, равный двум кеглям данного заголовка, за исключением расположения заголовка вверху страницы. Внизу каждого заголовка должен быть пробел, равный кеглю данного заголовка
Графические элементы, используемые в заголовках	Не используются
Колонтитулы: верхние нижние	Содержат название главы и раздела. Название главы располагают со стороны переплета Содержат номер страницы со стороны, противоположной переплету, с указанием на противоположной стороне номера версии, даты ее выпуска и наименования документа
Гарнитуры шрифтов, кегли и расположение колонтитулов: верхний нижний	Times Roman, кегль 12 п, колонтитулы расположены вверху каждой страницы за исключением титульного листа Times Roman, кегль 12 п, номер страницы кегль 12 п, колонтитулы расположены внизу каждой страницы за исключением титульного листа

Продолжение таблицы Н. 1

Элемент	Значение
Графические элементы колонтитулов: верхний нижний	Должен быть подчеркнут линией толщиной в 1 п с вертикальным пробелом в 1 п Должен быть надчеркнут линией толщиной в 1 п с вертикальным интервалом в 1 п
Надпись	Начинается с номера рисунка с двоеточием и текстом, например «Рисунок 1: . . .»
Гарнитуры шрифта, кегль и расположение надписей	Times Roman italics, кегль 10 п. Надписи должны быть расположены под рисунком
Таблицы	Ширина таблиц должна соответствовать формату текста основной части документа, а для их обрамления используют линии толщиной в 1 п
Гарнитуры шрифтов и минимальные кегли для таблиц	Times Roman, минимальный кегль в 8 п
Отчеты (сообщения)	Должны содержать правдоподобные (но не фактические) данные
Гарнитуры шрифтов и минимальные кегли для отчетов	Courier, минимальный кегль в 8 п
Компоновка отчетов	Должны быть представлены в горизонтальной (альбомной) компоновке без использования страниц-раскладок
Распечатки экранов: содержание оформление частичные (т. е. представляющие часть экрана)	В каждом поле распечаток экранов должны быть представлены правдоподобные (но не фактические) данные Не должно быть горизонтальных или вертикальных искажений. Их ширина должна соответствовать формату набора Должны быть в масштабе полноэкранных распечаток
Минимальная толщина линий, гарнитуры шрифтов и кегли для рисунков	0,5 п, шрифт Times Roman, минимальный кегль в 8 п
Рисунки	Рисунки и текст внутри них должны располагаться соответственно тексту основной части документа
Стиль текста уведомлений и предостережений	Стиль повествовательный, начинается со слова «Внимание:» или «Осторожно:»
Гарнитуры шрифтов, кегли и отступы для уведомлений и предостережений	Times Roman, кегль 24 п, расположение — по центру страницы, пробелы сверху и снизу, интервалы сверху и снизу — равные двум строкам
Справочный текст	Должны быть обеспечены возможности создания контекстных и расширенных справок, справок о клавишах, справок о справках и терминологических справок
Диалоговая документация	Должна содержать руководства для пользователя, командные справки, рекомендации по сообщениям и административную информацию

Окончание таблицы Н.1

Элемент	Значение
Сопутствующие материалы	Информация по одной тематике по возможности должна располагаться на одном экране
Подсветка и использование цвета	Цветовое оформление в диалоговой документации и справочных текстах не используют. Подсветку (более яркую цветовую тональность) используют только для заголовков
Диалоговая документация и справочный текст	Вверху отображаемого текста оставляют пустую строку (то есть между заголовком или верхом экрана и первой строкой текста). Формат текста — одноколонный
Заголовки диалоговой документации и справочного текста	Заголовки подсвечивают, используя более яркую цветовую тональность. Применяют только два уровня заголовков. Заголовки излагают в повествовательном стиле (см. 8.2.3.7.2). Сверху и снизу каждого заголовка оставляют пробел, равный одной строке
Текст основной части электронной документации	Должен быть выровнен по левой стороне, допускаются неровности по правому краю. Слева от каждой строки текста оставляют пробел, равный 20 символам
Правила навигации	Уровни расположения взаимосвязанной информации должны быть организованы и контролироваться так, чтобы пользователи могли легко возвращаться в исходную точку (пункт), содержание или указатель без блуждания в тексте документа
Клавиатура	Должны быть использованы следующие клавиши: F1 — для вызова справочной системы: Alt-F1 или Еsc — для выхода из справочной системы. Никакие данные, введенные пользователем ранее, не должны быть потеряны при возврате из справочной системы к основному экрану
* Цицеро — шрифт, кегль которого равен 12 п (~ 4,51 мм).

Н.3 Спецификация указателя

Н.3.1 О б щ и е п о л о ж е н и я
Каждый документ, содержащий более 32 страниц, должен иметь указатель.

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

Н.3.2 К а ч е с т в о
Указатель должен быть достаточно подробным, чтобы удовлетворить потребностям соответствующих аудиторий.
П р и м е ч а н и е — Указатель должен занимать от 5 % (для учебных руководств) до 10 % (для справочных руководств) общего объема данного документа. Следует рассмотреть возможность использования профессиональных классификаторов.

Н.3.3 С о с т а в (с о д е р ж а н и е) и о р г а н и з а ц и я у к а з а т е л я
Весь комплект документации должен иметь единый указатель, если иное не оговорено в плане докумен-тирования.

П р и м е ч а н и я
1    В качестве заголовков (элементов) указателя (слов или фраз, вносимых в указатель) следует использо¬вать объекты, выбранные из конкретного документа (например, «программное средство»).
2    Для представления одинакового понятия должен использоваться один и тот же термин.
3    В указателе могут быть использованы подзаголовки, описывающие некоторые аспекты основного заго-ловка.
4    Заголовки указателя должны представлять основные понятия из конкретного документа. Для них сле¬дует использовать имена существительные, при необходимости дополняя их прилагательными, другими суще-ствительными или глаголами. В качестве заголовков могут быть взяты машинные команды, использованные в документации и представленные в виде глагола.
5    Термины, состоящие из нескольких слов, следует применять как заголовки без разбивки их на подзаго¬ловки.
6    Следует избегать использования предлогов, если их отсутствие не приводит к неоднозначному понима¬нию термина.
7    Понятия, отражающие различные аспекты одного объекта, должны быть перечислены как подзаго¬ловки основного заголовка указателя.
8    Сокращения и обозначения должны быть расположены а алфавитном порядке (например, обозначе¬ние «BASIC» для «Beginner’s All-purpose Symbolic Instruction Code» между «Base» и «Bettery»).
9    Заголовки указателя должны располагаться в алфавитном порядке, пробел должен трактоваться как символ, предшествующий последующему (например, термин «Alt key» размещается перед «Alternative»).

Н.3.4 С п р а в о ч н ы е c с ы л к и
Для каждого элемента (заголовка, подзаголовка) указателя должны быть даны локальные ссылки при отсутствии перекрестных ссылок.
В справочных ссылках должен быть указан либо номер страницы документа (например, 1, 2), либо номера раздела, подраздела и т. д. (например, «2.22», «3.34»). При указании рисунков справочные ссылки могут быть даны на их номера.

П р и м е ч а н и я
1    Обычно пользователям удобнее пользоваться ссылками на страницы, чем на разделы документа.
2    Для элементов указателя не следует использовать большие перечни локальных ссылок. Максимально удобными для работы являются пять ссылок (например, 1, 33, 43, 99, 102). Во избежание длинных перечней локальных ссылок следует использовать подзаголовки.
3    Ссылки, подлежащие обсуждению, могут быть выделены шрифтом (гарнитурой, кеглем).
4    Если перечень подзаголовков охватывает несколько колонок (столбцов), вверху каждой колонки должно быть указано наименование основного заголовка со словом «продолжение».
5    Если используют особую последовательность нумерации страниц, она должна быть указана в указателе. Например, если нумерация начинается с номера каждой главы, данный номер должен быть указан в локаль¬ной ссылке, то есть «2—22, 3—34».
6    Если элемент указателя используют в нескольких частях документа, нумеруемых последовательно, в локальной ссылке должны быть указаны только первые и последние номера, разделенные тире (например, 3—11). Когда тире используют в нумерации страниц, для разделения страниц тире не используется (например, 3—6 до 3—8).

Н.3.5 П е р е к р е с т н ы е с с ы л к и
В перекрестных ссылках на сокращения, синонимы или альтернативные виды термина, выбранные из элементов указателя, следует использовать сокращение «См.» (например, проект — см. оформление).

П р и м е ч а н и е — Дополнительно перекрестная ссылка с сокращением «См.» может быть дана на другие элементы документа. За перекрестной ссылкой не следует использовать локальную ссылку.
Перекрестная ссылка со словами «См. также» может быть дана из более обширного термина на менее исчерпывающие термины, если не используется прямая локальная ссылка.

П р и м е ч а н и е — Перекрестные ссылки со словами «См. также» следует использовать для взаимоувяз¬ки терминов в интересах пользователя. Перекрестная ссылка со словами «См. также» под основным элементом указателя должна объединять ряд связанных элементов указателя, имеющих справочные ссылки. Например Рисунки 4
см. также графические элементы; распечатки экранов
индексирование 12
список 15
нумерация 2
Слова «См.» и «См. также» обычно выделяют курсивом.

Библиография

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

Соответствующие международные и национальные стандарты
[1] ИСО/МЭК 6592—2000 Информационная технология. Руководство по документированию прикладных ав-томатизированных систем
[2] BS 7649—93 Руководство по проектированию и выпуску документации пользователей прикладных программных средств

Общие положения
[3]    Barnum C. M. and Capliner S. Techniques for Technical Communicators, MacMillan, 1993
[4]    Brockmann R. J. Writing Better Computer User Documentation, Wiley, 1990
[5]    Brusaw C. T., Alred G. J. and Oliu W. E. Handbook of Technical Writing, St. Martin’s Press, 1993
[6]    Burnett R. E. Technical Communications, Wadsworth Publishing, 1994
[7]    Hackos J. T. Managing Your Documentation Projects, Wiley, 1994
[8]    Holtz H. The Complete Guide to Writing Readable User Manuals. Dow Jones-Irwin, 1988
[9]    Horton W. K. Illustrating Computer Documentation. Wiley, 1991
[10]    Simpson H. and Casey S. M. Developing Effective User Documentation: A Human Factors Approach. МсGraw- Hill, 1988
[11]    Weiss E. H. How to Write Usable User Documentation, Oryx Press < 1991
[12]    Zinsser W. On Writing Well, Harper and Row < 1994

Диалоговая документация и гипертекст
[13]    Bogan S., Farkas D. and Wellinske J. Developing On-Line Help for Windows, International Thomson Press, 1995
[14]    Brown C. M. Human-Computer Interface Design. Norwood, 1988
[15]    Helander (Ed). Handbook of Human-Computer Interaction. North Holland
[16]    Horton W. K. Designing and Writing On-line Documentation. Help Text to Hypertext. Wiley, 1990
[17]    Horton W. K. Designing and Writing On-line Documentation: Hypermedia for Self—Supporting Products, Wiley, 1994
[18]    Laurel and Mountford, The Art of Human-Computer Interface Design. Addison—Wesley, 1990
[19]    Van Der Veer and Mulder, Human-Computer Interaction. Springer—Verlag, 1988

Тестирование на практичность
[20] Dumas J. S. and Redish J. C. А Practical Guide to Usability Testing, Ablex Publishing, 1993
[21] Nielson J. Usability Engineering, AP Professional, 1993

УДК 681.3.06:006.354 ОКС 35.080 П85 ОКСТУ 5001
Ключевые слова: обработка данных, вычислительные машины, программные средства вычислитель¬ных машин, документирование, документация пользователя
Редактор Б. П. Огурцов Технический редактор Б. Н. Прусакова
Корректор Е. Д. Дульнева Компьютерная верстка Б. Н. Романовой
Изд. лиц. № 02354 от 14.07.2000. Подписано в печать 16.09.2002. Усл. печ. л. 5,58. Уч.-изд. л. 5,60. Тираж 440 экз.
С 7303. Зак. 754
ИПК Издательство стандартов, 107076 Москва, Колодезный пер., 14. http://www.standards.ru e-mail: info@standards.ru Набрано в Калужской типографии стандартов на ПЭВМ. Филиал ИПК Издательство стандартов — тип. «Московский печатник», 103062 Москва, Лялин пер., 6.
Плр № 080102

1    Область применения        1
2    Соответствие .         1
3    Нормативные ссылки        1
4    Определения        2
5    Управление качеством        4
6    Адаптация        5
7    Цели        5
8    Требования        5
8.1    Процесс документирования        5
8.2    Содержание спецификации стиля        12
Приложение А Перекрестные ссылки с ГОСТ Р ИСО/МЭК 12207         19
Приложение В Использование настоящего стандарта в договоре        19
В.1 Общие положения        19
В.2 Образец раздела договора        19
B.    3    Практическое применение настоящего стандарта        20
Приложение С Образец плана документирования. Документация пользователя для системы АВС
— административного управления магнитными лентами        20
C.    1    Введение        20
С.2 Область применения и ограничения        20
С.3 Оформление и стиль описания        20
С.4 Аудитория        21
С. 5 Проект содержания документации        21
С. 6 Номенклатура поставки        21
С.7 Авторские права         21
С.8 Транспортирование        21
С.9 Процесс разработки и контроль        21
С.10 Тиражирование        21
С.11 Проектанты        22
С.12 Ресурсы        22
С.13 Тестирование на практичность        22
С. 14 График работ         23
Приложение D Отношения между аудиториями, выданными заданиями, бумажной и диалого¬вой документацией        23
Приложение Е Рекомендации по написанию на английском языке документации, подлежащей
последующему переводу        26
Е.1 Общие положения        26
Е.2 Терминология        26
Е.3 Стиль перевода        26
Е.4 Физические факторы        27
Е.5 Диалоговая информация        27
E.    6    Культурные факторы        27
Приложение F Оценка проекта        28
F.    1    Общие положения        28
F.2 Поминутный и почасовой методы        28
F.3 Метод нисходящего проектирования        29
Приложение G Оценка плана документирования        30
Приложение Н Образец спецификации стиля        30
Н.1 Общие положения        30
Н.2 Элементы стиля        30
Н.3 Спецификация указателя        34
Библиография        36
Тематический указатель        37
Введение
Существующие стандарты можно отнести к двум основным типам:
a)    стандарты на продукцию, определяющие ее характеристики и требования к ней;
b)    стандарты на процессы, определяющие конкретные методы создания продукции.
Возрастающий масштаб применения программных средств и их сложность вызывает необходи¬мость наличия полной, точной и понятной документации на эти средства, доступной пользователям. Настоящий стандарт определяет способ достижения данной цели, устанавливая работы (что должно быть сделано и исполнителя), связанные с качеством документации пользователя программных средств.
Документация часто рассматривает нечто, разрабатываемое после создания конкретного про¬граммного средства. Однако с точки зрения качества разработки программной документации она должна рассматриваться как неотъемлемая часть процесса создания данного программного средства. При надлежащем подходе к данной проблеме требуется достаточно сложная работа по планированию документирования. Целью настоящего стандарта является стимулирование разработчиков программных средств к надлежащему использованию процесса документирования. Стандарт также представляет пользо-вателям метод определения надлежащего применения процесса документирования при создании конк-ретного программного средства.
Основной работой по настоящему стандарту является создание комплексного плана разработки документации, реализация которого обеспечивает лучшее документирование программного средства. Для соответствия настоящему стандарту данный план должен включать в себя требования (специфика¬цию) к стилю оформления документов. Настоящий стандарт не определяет состав данных требований (то есть компоновку конкретного документа или используемый шрифт), но устанавливает их диапазон. Стандарт также определяет виды информации, представляемой заказчиком разработчику документа¬ции (документатору) для проверяющих и распространяющих документацию.
Более подробная информация по данному вопросу приведена в библиографии.
П р и м е ч а н и я
1    Основной стандарт дополнен справочными приложениями, библиографией и тематическим указате¬лем.
2    Исходный стандарт ИСО/МЭК 15910 разработан на основе австралийского стандарта AS 4258:1994.
3    Перечень дополнительных публикаций, связанных с тематикой настоящего стандарта, приведен в библиографии (см. [1] — [21]).
Информационная технология
ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА
Information technology. Software user documentation process
Дата введения 2003—07—01
1    Область применения
Настоящий стандарт определяет минимально необходимый процесс создания документации пользо-вателя всех видов для программного средства, имеющего интерфейс пользователя. Данные виды охва¬тывают печатную документацию (например, руководства пользователя и краткие справочные карты), диалоговую (оперативную) документацию, справочный текст («хелпы») и системы диалоговой доку¬ментации.
Стандарт соответствует требованиям 6.1 ГОСТ Р ИСО/МЭК 12207.
Применение настоящего стандарта должно обеспечить разработку документации, удовлетворяю¬щей потребностям пользователя.
Стандарт предназначен для разработчиков и потребителей документации пользователя.
Настоящий стандарт используется для печатной документации, а также для справочных экранов, справочной системы обеспечения поставки, справочной информации и т. д.
Стандарт предназначен для применения при двусторонних отношениях и может быть использо¬ван, если обе стороны корпоративно связаны. Стандарт также может быть использован одной из сторон для самоконтроля.
П р и м е ч а н и е — В приложении В приведены более подробные рекомендации по применению настоящего стандарта в договоре между заказчиком и разработчиком документации.
2    Соответствие
Соответствие настоящему стандарту определяют по результатам демонстрации выполнения реали-зацией процесса, описанного в разделе 8.
3    Нормативные ссылки
В настоящем стандарте использованы ссылки на следующие стандарты:
ГОСТ 2.301—68 Единая система конструкторской документации. Форматы
ГОСТ Р ИСО 9127—94 Системы обработки информации. Документация пользователя и инфор¬мация на упаковке для потребительских программных пакетов
ГОСТ Р ИСО/МЭК 12119—2000 Информационная технология. Пакеты программ. Требования к качеству и тестирование
ГОСУДАРСТВЕННЫЙ
СТАНДАРТ
РОССИЙСКОЙ ФЕДЕРАЦИИ
ГОСТ Р ИСО/МЭК 12207—99 Информационная технология. Процессы жизненного цикла про-граммных средств
ИСО 216—75* Бумага писчая и классы печатных материалов. Размеры обрезки. Серии А и В.
* Оригинал международного стандарта — во ВНИИКИ Госстандарта России. Издание официальное
4 Определения
В настоящем стандарте использованы следующие термины с соответствующими определениями.
4.1    А4, А5: Размеры сторон листа 210297 мм и 148210 мм соответственно (см. ИСО 216, ГОСТ 2.301).
4.2    заказчик (acquirer): Организация, которая приобретает или получает систему, программный продукт или программную услугу от поставщика (3.1 ГОСТ Р ИСО/МЭК 12207).
П р и м е ч а н и е — Заказчиком может быть: оптовый или розничный покупатель, клиент, собственник или пользователь. В контексте настоящего стандарта заказчиком является сторона, запрашивающая докумен¬тацию. Отметим, что наличие у заказчика документации не является обязательным. Заказчик и разработчик документации могут быть представителями одной организации, или заказчиком может быть разработчик дан¬ного программного средства.
4.3    аудитория (audience): Категория пользователей, предъявляющих к документации одинаковые или аналогичные требования и характеристики (например, в части использования документации, ее назначения, уровня обучения, возможностей и опыта персонала), определяющие содержание, струк¬туру и назначение данной документации.
П р и м е ч а н и е —Одна и та же программная документация может использоваться различными аудиториями (например, руководством, операторами по вводу исходных данных или сопроводителями).
4.4    изучение аудитории (audiеnce research): Планируемый процесс опроса потенциальных пользо-вателей и анализа его индивидуальных и интегральных результатов.
П р и м е ч а н и е — Целью данного процесса является определение возможностей, квалификации, опыта, предубежденности и преимуществ потенциальных читателей документа.
4.5    В5: Размеры сторон листа 176250 мм (см. ИСО 216).
4.6    вспомогательный материал (back matter): Материал, содержащийся в конце книги или руко-водства, например, тематический указатель.
4.7    фотошаблоны (camera-ready originals):Hабор изображений на бумаге, фотопленке или другом носителе, с которого может быть сделана фотокопия, где каждое изображение содержит все необходи¬мые текстовые и графические элементы одной страницы печатного документа. скомпонованные долж¬ным образом.
4.8    дата пересмотра (cut-off date): Дата, по истечении которой все изменения, внесенные в программные средства, описываются в новой редакции документации, более верной по сравнению с действующей.
4.9    номенклатура поставки (deliverables): Объекты (элементы, изделия и т. д.), поставляемые заказчику по условиям договора.
4.10    документ (document): См. элемент документации (4.26).
4.11    документация (documentation): Печатные руководства пользователя, диалоговая (оператив¬ная) документация и справочный текст («хелпы»), описывающие как пользоваться программным продуктом.
4.12    персонал разработчиков документации (documentation development staff): Весь персонал, привлекаемый на любом этапе планирования, написания, редактирования и выпуска документации.
П р и м е ч а н и е — Данный термин охватывает коллектив авторов, оформителей, иллюстраторов и администрации проекта.
4.13    план документирования (documentation plan): Документ, в котором излагаются необходимые элементы проекта документирования.
4.14    документатор (documenter): Сторона, создающая документацию.
П р и м е ч а н и е — В настоящем стандарте не используют термин разработчик (developer) (в смысле 3.8 по ГОСТ Р ИСО/МЭК 12207), так как в случае документирования разработчик программного средства часто является заказчиком документации, и использование термина разработчик может привести к разночтению. Поэтому используют термин документатор.
4.15    электронная копия (electronic copy): Компьютерный диск или другой машиночитаемый носитель информации, содержащий файл или файлы, с которого(ых) может быть распечатан доку¬мент.
4.16    n-штрих (en dash): Штрих, имеющий такую же ширину, как и строчная буква «n».
4.17    концевые примечания (endnotes): Примечания, собранные в конце главы или документа.
4.18    страница-раскладка (foldout): Страница, сложенная так, что ее задняя часть шире передней (немного превышает основной формат), которую можно развернуть.
4.19    нижний колонтитул (footer): Справочная(ые) строка(и) под текстом страницы, указываю¬щая^) на ее содержание (например, номер страницы).
4.20    сноска (footnote): Помещаемый внизу страницы (колонки) текст (примечание, библиогра¬фическая ссылка и т. д.), связанный с основным текстом знаком сноски (цифровым номером, звездоч¬кой), закрываемым круглой скобкой, набираемый обычно шрифтом пониженного кегля по сравне¬нию со шрифтом основного текста и отделяемый от него пробелом или пробелом с тонкой короткой линейкой.
4.21    вводный материал (front matter): Начальная часть или глава издания, например, титульный лист и содержание.
4.22    верхний колонтитул (header): Справочная(ые) строка(и) над текстом страницы.
4.23    заголовок (heading): Название внутреннего подраздела издания, определяющее тему, рас-крываемую в последующем тексте.
4.24    справочная система (help system): См. 4.32.
4.25    справочный текст (help text): Текст, облегчающий и убыстряющий пользователю, при экс-плуатации программного средства, поиск содержащихся в издании объектов, автоматически выбирае¬мый в зависимости от контекста, в котором он вызывается, т. е. справочный текст контекстно зависим.
4.26    элемент документации (item of documentation): Целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в крат¬кой справочной карте) в заданном формате.
4.27    справочная ссылка (location reference): Метка, выделяющая заголовок или подзаголовок в тематическом (предметном) указателе, показывающая, к какой части документа они относятся.
4.28    измененный документ (изменение документа) (mark-up): Документ, содержащий заполнен¬ные листы изменений, а также процесс создания такого документа.
4.29    оригинал-макет (mechanicals): Оригинал, напечатанный как образец для набора, содержа¬щий подробные текстовые, переплетные, издательские и компоновочные характеристики печатной продукции (издания).
4.30    навигация (navigation): Способ перехода пользователя от одной части прикладных программ¬ных средств к другой.
4.31    диалоговая документация (on-line documentation): Информация, доступная пользователю при эксплуатации программного средства, которая не обязательно привязана к конкретному контексту (см. также 4.25).
4.32    система диалоговой документации или справочная система (on-line documentation system or help system): Часть программы (иногда отдельная программа), запрашиваемая пользователем и позво¬ляющая ему просматривать части диалоговой документации или справочного текста (см. также 4.25 и 4.31).
4.33    концевая висячая строка (orphan): Строка части текста (главы, раздела и т. д.) единственная на странице (полосе).
4.34    бумажный документ (orphan): Часть документации, представляемая в печатном виде.
4.35    элиз (доп. пиксель) (pixel): Наименьший элемент изображения на экране дисплея; сокраще¬ние от «элемент изображения» («picture element»).
4.36    точка (point): Единица типометрической типографской системы, выражаемая расстоянием по вертикали и содержащая в 1 мм приблизительно 2,8 точек (в одном дюйме приблизительно 72 точки).
4.37    процесс (process): Набор преобразующий исходные данные в выходные результаты (3.17 ГОСТ Р ИСО/МЭК 12207).
4.38    продукция (product): Полный набор компьютерных программ, процедур и соответствующих им документации и данных, предназначенный для поставки пользователю.
П р и м е ч а н и е — Используют также термин «программный продукт».
4.39    производство (production): Предварительная подготовка текста к переводу его в фотошабло¬ны, законченные справочные тексты или диалоговую документацию.
4.40    гранки (proof): Окончательная редакция бумажного документа, представленная перед печа¬тью заказчику для рассмотрения и утверждения.
П р и м е ч а н и е — При отсутствии замечаний окончательный документ должен быть во всех отноше¬ниях идентичен гранкам, за исключением вида бумаги, переплета и цветового оформления. Гранки обычно являются фотокопией фотошаблонов.
4.41    прототип (prototype): Модель или предварительная реализация части программного средства, пригодная для оценки проекта системы, ее потенциальных рабочих характеристик, производства или лучшего понимания требований к программному средству.
4.42    оборот (листа) (recto): Страница нижняя по отношению к левой или правой верхней стороне крышки переплета.
4.43    распечатка экрана (screen dump): Предполагаемое изображение, которое пользователь дол¬жен видеть на экране при эксплуатации программного средства.
4.44    система (system): Комплекс процессов, технических и программных средств, устройств, обслуживаемый персоналом и обладающий возможностью удовлетворять установленным потребностям и целям (3.31 ГОСТ Р ИСО/МЭК 12207).
4.45    содержание (table of contents): Указатель заголовков издания с указанием номеров страниц в порядке их возрастания.
4.46    таблица действующих страниц (лист изменений) (table of effective pages): Перечень последних версий номеров каждой замененной страницы бумажного документа. При замене отдельных страниц в перечне указывают старые и новые номера страниц.
4.47    план выбора группы проектантов (team selection plan): Документ, устанавливающий требова¬ния к квалификации и опыту персонала, разрабатывающего документацию.
4.48    страница-развертка (throwclear): Страница-раскладка, выполненная таким образом, что в развернутом виде и закрытом издании (книге, руководстве) доступна для обозрения (чтения) совме¬стно с предыдущими страницами.
4.49    практическая лаборатория (usability laborato^): Комплекс аналитических и исследовательс¬ких помещений, оснащенных видео- и аудиооборудованием для регистрации ответов на запросы пользо¬вателей.
4.50    тестирование на практичность (usability testing): Формальный процесс оценки соответствия документации установленным требованиям.
4.51    интерфейс пользователя (user interface): Интерфейс, обеспечивающий возможность обмена информацией между человеком и техническими или программными компонентами вычислительной системы.
4.52    пользователь (user): Лицо или организация, которые используют действующую систему для выполнения конкретной функции (3.34 ГОСТ Р ИСО/МЭК 12207).
П р и м е ч а н и е — см. также 4.3.
4.53    разворот (листа) (verso): Две смежные страницы раскрытого издания, левая и правая.
4.54    разделитель активный (white space, active): Пространство (за исключением полей), охватыва¬ющее текстовые и графические элементы, разделяющее текст, отделяющее тематические и подтемати- ческие составляющие текста, указывающее в тексте тематические и иерархические отношения, выде¬ляющее соответствующую информацию и облегчающее чтение текста.
4.55    разделитель пассивный (white space, passive): Верхнее, нижнее, левое и правое поля, окружа¬ющие текст.
4.56    начальная висячая строка (widow): Первая строка части текста (главы, раздела и т. д.), завершающая последнюю строку на странице (полосе).
5 Управление качеством
Если разработку программного средства документируют в соответствии со стандартом по управ¬лению качеством, положения данного стандарта в равной мере применяют как к самой разработке, так и к соответствующей документации.
П р и м е ч а н и е — Даже если стандарт по управлению качеством не указан в договор (контракте), документаторы стремятся использовать систему управления качеством, аттестованную на соответствие дан- ному(ым) стандарту(ам). Относительно качества программного средства в целом см. ГОСТ Р ИСО/МЭК 12119.
Адаптация
Настоящий стандарт определяет одну из реализаций процесса документирования, описанного в ГОСТ Р ИСО/МЭК 12207, и может быть адаптирован к условиям конкретных проектов (см. приложе¬ние В).
Цели
Настоящий стандарт по существу является стандартом на процесс. Стандарт не определяет компо¬новку конкретного документа, его содержание и другие аспекты комплектности документации, одна¬ко он устанавливает метод планирования и проведения процесса документирования.
Требования
8.1 Процесс документирования
8.1.1    О б щ и е п о л о ж е н и я
Процесс документирования должен быть выполнен в два этапа в последовательности, представ¬ленной на рисунке 1 в затененных прямоугольниках. Поэтапные работы не выполняются одновременно. На отдельных этапах работы могут проводиться параллельно. Возможные итерации работ показаны пунктирными линиями.
Когда минимальный состав документации определяется заказчиком (например, с использова¬нием ГОСТ Р ИСО 9127 или ИСО/МЭК 6592 [1]), это должно быть учтено документатором при разработке плана документирования.
8.1.2    П р е д с т а в л е н и е и с х о д н ы х м а т е р и а л о в
Заказчик должен обеспечивать документатору доступ:
a)    ко всем соответствующим спецификациям, форматам записей, компоновкам экранов и отче¬тов, выходным результатам работы средств автоматизации программирования (САSE tool) и другой информации, необходимой для подготовки документации;
b)    к рабочей копии программного средства (при необходимости);
c)    к аналитикам и программистам, включая своевременное правильное решение вопросов, воз-никающих у персонала разработчиков документации;
d)    к типичным пользователям (по возможности) для анализа аудитории и тестирования на практичность.
В обязанности документатора входит обеспечение плодотворности контактов с разработчиками программных средств заказчика, гарантирующее как минимум понимание сути выпускаемой продук¬ции и соответствующих ей аудиторий.
П р и м е ч а н и е — Документатор не отвечает за разработку, проверку или корректировку исходных материалов, а только за их получение.
Независимо от того, является ли документатор одновременно разработчиком программного сред¬ства, заказчик должен обеспечить его копиями всех применяемых стандартов, руководствами по сти¬лям и форматам, а также соответствующими материалами (если они не являются общедоступными). Документатор должен обеспечить данными материалами соответствующий персонал разработчиков документации.
Обязанностью разработчика является обеспечение полноты, правильности и актуальности всех материалов, предъявляемых разработчику на момент их поставки.
Разработчик должен гарантировать, что представление документатору данных материалов не на¬рушает прав интеллектуальной собственности любой третьей стороны.
Документатор должен предпринять соответствующие шаги по сохранению материалов, представ-ленных заказчиком, обеспечить защиту информации о требованиях заказчика и возвратить все мате¬риалы заказчику по завершении проекта документирования.
П р и м е ч а н и е — В ряде случаев нет необходимости возвращать все материалы; данный вопрос должен быть оговорен в договоре. В ряде случаев требуется сохранить конфиденциальность и секретность пре¬доставленных материалов. В договоре должны быть установлены уровни (грифы) конфиденциальности или секретности материалов, представляемых заказчиком документатору.

Рисунок 1 — Обзор процесса документирования

8.1.3 П л а н д о к у м е н т и р о в а н и я
8.1.3.1 Общие положения
Документатор должен подготовить план документирования, в котором должны быть определены задания, выполняемые при создании конкретной документации. Данный план должен быть официаль¬но согласован заказчиком, что подтверждает полный учет в этом плане всех требований заказчика.
П р и м е ч а н и е — Обычно план документирования должен охватывать весь комплект документации, например руководства пользователя, диалоговую документацию, справочные тексты и краткие справочные карты. Пример плана приведен в приложении С. Процесс проектирования документации описан в приложе¬нии D.
В плане документирования должны быть четко описаны область применения и ограничения по использованию планируемой документации, а также основные решения по анализу и проектированию этой документации. В плане также должны быть определены процессы и проверки, выполняемые при разработке документации.
План документирования должен охватывать следующие вопросы (но не ограничиваться ими):
a)    рабочее наименование, назначение, область применения и ограничения по использованию планируемой документации;
b)    спецификацию стиля в соответствии 8.2;
c)    определение аудитории пользователей (см. 8.1.3.2);
d)    обоснование причин использования документации данной аудиторией и ее целевое назначение;
e)    содержание (план-проспект) документации, с оценкой ее постраничного объема, и соответ¬ствующие уточнения для других машинных носителей документации;
f)    номенклатуру поставки — число печатных копий, наличие электронных копий, форматы дисков и файлов (включая версии программных средств) и откуда они могут быть поставлены;
g)    установление собственника авторских прав на документацию и любых других прав собствен¬ности.
П р и м е ч а н и е — Вопрос прав собственности является сложным. Во всех договорах на документацию должны быть указаны собственники соответствующих прав. При этом может быть указана последующая воз-можность передачи авторских прав от документатора к заказчику. Передача авторских прав целесообразна при определении места и способа тиражирования документации;
h)    обеспечение перевода документации на другие языки.
П р и м е ч а н и е — Подробнее см. в приложении Е;
i)    уровни (грифы) секретности и конфиденциальности (при необходимости);
j) процедуры и проверки, могущие влиять на процесс разработки документации, включая, при необходимости, хранение, поиск, резервирование, передачу и оценку качества;
k) методы и средства производства (тиражирования) и используемые версии данных средств;
l) структуру коллектива разработчиков документации и, возможно, плана выбора данной струк¬туры.
П р и м е ч а н и е — Конкретные лица привлекаются на различных этапах написания и производства (тиражирования) документации в зависимости от уровня своего опыта и знаний. Например, может быть необ-ходимым хорошее знание автором документируемой системы и опыт в написании документации; для редакто¬ра может потребоваться только опыт редактирования, но не знание системы; от компоновщика (оформите¬ля) может не требоваться других знаний кроме знания средств оформления;
m) взаимосвязи (подчиненности) проекта;
n) почасовую загрузку и зарплату персонала (руководство по оценке этих факторов приведено в приложении F);
0)    требования к проектным ресурсам, включая информационные и прочие ресурсы, представ¬ляемые заказчиком, и срокам их представления;
р) метод передачи документатору информации об изменениях программного средства в процессе его разработки;
q) планы контроля изменений и сопровождения документации (факультативно);
r) планы проверки документации после ее создания;
s) календарное планирование (графики) по контрольным точкам (milestones), включая (при необходимости):
1)    утверждение плана документирования,
2)    подготовку, проверку и корректировку проекта каждого документа,
3)    тестирование на практичность,
4)    подготовку оригиналов фотошаблонов,
5)    распечатку, переплетение и распространение документации.
При необходимости каждый из пунктов плана должен быть описан для каждого элемента доку-ментации.
П р и м е ч а н и я
1    Полезно также включить в план документирования образцы аналогичной документации, выпускаемой документатором или другими сторонами, чтобы показать ее стили и компоновку.
2    План документирования должен быть подготовлен и утвержден до начала разработки документации, чтобы гарантировать согласование всеми сторонами поставленных задач и используемых методов. После утверждения плана он должен быть доведен до всех заинтересованных сторон, включая персонал разработ¬чиков документации, а также заказчика и субподрядчиков (например, печатников, наборщиков, переводчи¬ков).
8.1.3.2    Определение аудитории пользователей
План документирования должен включать определение аудитории(й) пользователей документа¬ции, уровня образования, способностей, подготовки, опыта данных пользователей и других характе¬ристик, связанных с содержанием, структурой и использованием документации.
Обычно имеется ряд различных групп пользователей, преследующих различные цели при ис-пользовании конкретной документации. Каждый тип пользователей, включая их характеристики и задачи, решаемые ими при помощи документации, должен быть определен отдельно.
П р и м е ч а н и я
1    Данные об определении аудитории пользователей могут быть получены из:
a)    результатов изучения аудитории, проведенного заказчиком или документатором;
b)    описаний, представляемых заказчиком;
c)    определений аудитории, полученных из других источников.
2    По возможности персонал разработчиков документации должен организовать встречи с типовыми пользователями в их рабочей обстановке и обследовать их работу.
8.1.3.3    Контроль плана документирования
После официального согласования плана документатор должен нести ответственность за контроль и распространение данного плана. Документатором должен быть составлен список по распространению учтенных копий данного плана.
В случае внесения в план последующих изменений (согласованных документатором и заказчи¬ком) документатор должен гарантировать получение этих изменений всеми держателями учтенных копий.
П р и м е ч а н и е — Вследствие проблем, возникающих при наличии устарелых копий плана, докумен¬татор должен запретить его несанкционированное копирование и предусмотреть процедуры аудита всех обнов¬ляемых копий плана.
8.1.4 П р о в е р к а (а н а л и з)
8.1.4.1 Общие положения
Соответствующие проверки должны проводиться заказчиком с привлечением документатора (при необходимости).
П р и м е ч а н и е — Целью проверки является гарантирование полноты и правильности представленных материалов и удовлетворения ими потребностей заказчика в соответствии с условиями договора и планом документирования.
Проверка должна проводиться персоналом заказчика, обладающим соответствующей квалифика¬цией и полномочиями по предложению изменений в документацию и утверждению измененной доку¬ментации.
П р и м е ч а н и е — Заказчик должен ограничить количество проверяющих лиц до пределов, необходи¬мых для реализации функции проверки.
При утверждении (согласовании) каждого проекта документации заказчик должен гарантировать правильность решения вопросов ее защиты и законности.
Документация для проверки должна представляться с сопроводительным письмом от документатора, в котором должны быть указаны цели проверки и обязанности проверяющей стороны (эксперта).
П р и м е ч а н и я
1    Качество документации и успешность проверок повышаются при наличии хороших контактов между заказчиком и документатором в процессе разработки документации. При этом должно быть предусмотрено неформальное обсуждение возникающих вопросов и по возможности раннее представление заказчику образ¬цов документации или предварительных материалов.
2    Договор может быть скорректирован при необходимости внесения в него изменений, не связанных с областью действия договора или плана документирования.
3    Отметим, что проведение проверки не освобождает документаторов от обязанностей по гарантирова¬нию максимально возможной полноты и точности документации.
4    Непосредственно перед представлением любой публикации на утверждение, в ней должны быть обнов¬лены все распечатки экранов для гарантирования ее актуальности.
5    Результаты проверок представляются заказчиком документатору в виде пометок в проекте документа¬ции или письменных комментариев по его содержанию. Заказчик должен хранить копии всех вносимых измене¬ний для сравнения их с последующими проектами документации. Представляемые заказчиком комментарии должны быть в виде, позволяющем персоналу разработчиков документации внести предлагаемые изменения в проект документации без дальнейших пояснений.
6    Для больших сложных систем или систем, разрабатываемых одновременно с документацией, может быть необходимо более двух проектов документации и наличие гранок. В этом случае максимальное число проектов (редакций) документации должно быть оговорено между заказчиком и документатором и указано в плане документирования.
7    При проверке проектов документации используют редакционные разметки (знаки, цвета, разметка шрифтов и прочее), Целью редакционных разметок является выделение частей публикации, нуждающихся в уточнении. Тем самым предотвращается необходимость в повторных проверках проектов. Настоятельно реко¬мендуется для внесения редакционной разметки использовать средства автоматизированного сравнения доку¬ментов (при их наличии).
При редакционной разметке рекомендуется:
a)    не вносить разметку в распечатку первого проекта (редакции) новой публикации;
b)    использовать разметку для показа изменений, вносимых в оригинал проверяемой публикации;
c)    во втором проекте использовать разметки с номером 1 для указания изменений, внесенных по ре¬зультатам проверки первой редакции;
d)    в третьем проекте использовать разметки с номером 2 аналогично номеру 1;
e)    после принятия третьего проекта все разметки в нем должны быть сохранены до проверки гранок публикации.
8.1.4.2    Проверка плана документирования
Данная проверка должна гарантировать, что документация, предусмотренная планом документи-рования, после его выполнения будет удовлетворять целям заказчика. При утверждении плана доку-ментирования заказчик согласовывает все характеристики номенклатуры поставки, предусмотренной планом.
П р и м е ч а н и е — Заказчики должны уделять особое внимание структуре, полноте и практичности документации в соответствии с планом-проспектом ее содержания. План документирования должен быть про¬верен и утвержден (согласован) до начала работ над первым проектом документации. Рекомендации по оценке плана приведены в приложении G.
8.1.4.3    Проверка первой редакции
Первая редакция (проект) должна содержать основную часть документации в соответствии с планом документирования, а также содержание, приложения и словарь (словник, определения). При применении средств автоматического создания указателя каждая его предметная рубрика (индекс) должна ссылаться на конкретные пункты документации. Орфография, пунктуация, стиль и компонов¬ка документации должны соответствовать указанным в плане документирования.
Первый проект документации должен быть проверен заказчиком. Данная проверка предназначена для контроля технической правильности и полноты документации и должна гарантировать соответ¬ствие данного проекта заданиям плана документирования. Также проверяют соответствие орфографии, пунктуации, стиля и компоновки документации требованиям плана документирования.
При утверждении первого проекта заказчик согласовывает техническую правильность, структу¬ру, понятность и полноту документации, исключая предложенные изменения.
П р и м е ч а н и я
1    Перед предъявлением заказчику первый проект должен быть отредактирован по следующим причи¬нам:
a)    чтобы проверяющий не отвлекался на корректировку типографских и компоновочных ошибок;
b)    чтобы любые технические неточности, внесенные при редактировании, были обнаружены прове¬ряющим.
2    Проект должен быть проверен на соответствие выданным заданиям, указанной аудитории, содержа¬нию и другим характеристикам, согласованным в плане документирования. Перед возвратом первого проекта с комментариями документатору заказчик должен быть уверен, что проект, включая все корректировки, соответствует плану документирования.
8.1.4.4    Проверка второго проекта
Во второй проект документации должны быть включены все изменения, согласованные с заказ¬чиком при проверке первого проекта, а комплектность поставки второго проекта по возможности должна соответствовать номенклатуре поставки, оговоренной в плане документирования.
Данная проверка предназначена для контроля правильности внесения в документацию всех изме-нений, указанных заказчиком на этапе первого проекта.
При утверждении второго проекта заказчик согласовывает все аспекты документации за исклю¬чением физической формы представления документации по данному проекту, которая может не соот¬ветствовать указанной в номенклатуре поставки.
П р и м е ч а н и е — При утверждении второго проекта заказчик должен быть уверен, что по данному проекту (включая внесенные изменения по результатам проверки первого проекта) могут быть изготовлены гранки.
8.1.4.5 Проверка гранок
В подготовленные гранки документации должны быть внесены все изменения, указанные заказ¬чиком при проверке второго проекта.
Данная проверка предназначена для контроля правильности внесения в документацию всех изме-нений, указанных заказчиком на этапе второго проекта. Любые обнаруженные заказчиком несоответ¬ствия должны быть немедленно доведены до сведения документатора, который должен соответствую¬щим образом модифицировать документацию и представить копии измененных разделов заказчику для дальнейшей проверки.
Утверждая (согласовывая) гранки документации, заказчик подтверждает готовность конкретного документа к производству (тиражированию).
8.1.5 Т е с т и р о в а н и е д о к у м е н т а ц и и н а п р а к т и ч н о с т ь
8.1.5.1    Общие положения
В плане документирования должен быть указан требуемый уровень тестирования документации на практичность.
Минимально должно быть проведено одно тестирование на практичность документации, исполь-зуемой для выпускаемой версии программного средства.
П р и м е ч а н и я
1 Тестирование на практичность следует рассматривать как дополнения к проводимым проверкам и анализам документации. Подобное тестирование при разработке должно проводиться на прототипе докумен¬тации, наиболее полно моделирующем ее окончательную версию.
2    При установлении условий данного тестирования должен быть полностью указан стандарт на характе-ристики практичности, по которому проводят измерение. Следует также определить соответствующий(е) ме- тод(ы) измерения и процесс описания результатов замеров.
3    При необходимости в плане документирования следует определить среду тестирования, которая долж¬на полностью соответствовать эксплуатационной среде конечного пользователя.
4    Тестирование на практичность может быть использовано для оценки (измерения) практичности по ГОСТ Р ИСО/МЭК 12119.
8.1.5.2    Планирование
В плане документирования должны быть полностью описаны условия тестирования, включая:
a)    этап(ы) жизненного цикла разработки, на котором(ых) должно проводиться тестирование;
b)    цели тестирования;
c)    используемые показатели (например, время реакции задач);
d)    среду тестирования;
e)    число и вид привлекаемых пользователей;
f)    процесс описания результатов тестирования и рекомендаций по ним;
g)    процесс обеспечения реализации рекомендаций по результатам тестирования;
h)    процесс доведения результатов тестирования до всего персонала разработчиков документации и заказчика;
i)    обязанности персонала разработчиков документации, участвующего в тестировании;
j) процесс определения необходимости последующего тестирования.
П р и м е ч а н и я
1 При проведении тестирования документации на практичность необходимо проверить соответствие документов конкретному программному средству. Для повышения эффективности данного тестирования его необходимо проводить как можно раньше, внося необходимые изменения как в само программное средство, так и в его документацию.
2 При составлении графика тестирования необходимо учитывать тестирование отдельных компонентов (частей) программного средства и выполняемых ими функций.
8.1.5.3    Программные средства
Когда тестирование запланировано до завершения разработки программного средства, при его проведении должна быть использована рабочая модель или прототип данного средства. При проведении тестирования после завершения разработки программного средства следует использовать выпускаемую версию данного программного средства.
8.1.5.4    Типовые пользователи
В проведении тестирования документации на практичность должны участвовать представители заказчика. Данными представителями должны являться лица, имеющие тот же опыт (навыки, образо¬вание и т. д.), что и пользователи из конкретной аудитории. Цели их участия в тестировании должны быть определены заказчиком.
П р и м е ч а н и е — Для участия в тестировании по возможности должны быть привлечены лица из конкретной аудитории.
8.1.6    Д о к у м е н т а ц и я, р а з р а б о т а н н а я д р у г и м и к о м п а н и я м и п о с у б п о д р я д а м
Документатор (головной подрядчик) должен гарантировать соответствие документации, разрабо-танной субподрядчиками, настоящему стандарту, плану документирования и договору.
В отношении документации, разрабатываемой субподрядчиком, документатор выступает в роли заказчика, а субподрядчик — документатора.
П р и м е ч а н и е — Документатор должен заключить соглашения с субподрядчиками в соответствии с настоящим стандартом.
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    Разрешающая способность типографского или лазерного способа печати
Должна быть определена минимально допустимая разрешающая способность печати (количество точек в 1 дюйме/1 мм).
П р и м е ч а н и е — Минимально рекомендуемой является разрешающая способность 300 точек/дюйм.
8.2.3.1.5    Ширина внутреннего поля
Должно быть определено расстояние от полосы набора до корешка переплета.
8.2.3.1.6. Ширина внешних полей
Должны быть определены расстояния от полосы набора до внешних краев страницы.
8.2.3.1.7    Цвета красок
Должны быть определены цвета красок, используемых при печати.
П р и м е ч а н и е — Если в плане документирования или в договоре указано несколько цветов, любой документатор, не компетентный в области многоцветной печати, должен заранее (до предъявления гранок заказчику) обратиться за консультацией к соответствующим специалистам.
8.2.3.1.8    Цвет, масса и качество бумаги
Должны быть определены цвет, масса и качество (номер) бумаги, используемой для документа¬ции.
П р и м е ч а н и е — Если требуется конкретный номер бумаги, это должно быть указано.
8.2.3.1.9    Разделители
Если в документации применяются разделители, должны быть указаны их цвет, масса и качество. В спецификации стиля должна быть определена информация, печатаемая на разделителях, а также их формат, ориентация и используемый шрифт.
8.2.3.1.10    Метод воспроизведения (тиражирования) и качество
Должен быть указан метод тиражирования документации (печатный, фотокопировальный и т. д.), а также соответствующие ему показатели качества.
8.2.3.1.11    Переплет
Должен быть указан метод переплетения документации.
8.2.3.2    Схемы нумерации
8.2.3.2.1    Нумерация страниц
Должна быть определена схема нумерации страниц.
П р и м е ч а н и я
1    Каждая страница должна иметь индивидуальный номер. Номера страниц должны быть проставлены в порядке их брошюрования.
2    При брошюровке документа с заменяемыми страницами схема нумерации должна учитывать номер текущей главы (раздела) с номером страницы в данной главе (разделе), например «1—1», «1—2» и т. д. (тем самым обеспечивается вставка страниц в документ без перенумерации всех последующих страниц).
3    В случае брошюровки документа без замены страниц используют порядковую номерацию, например «1», «2» и т. д. Иногда для нумерации страниц содержания используют другую схему («i», «ii» и т. д.). Следует избегать схожих методов нумерации страниц вспомогательного (указателя и т. д.) и вводного материалов, так как это может привести к неоднозначности в случае изъятия или вставки страниц.
8.2.3.2.2    Нумерация таблиц и рисунков
Должны быть определены схемы нумерации рисунков и таблиц (при необходимости их нумера¬ции).
П р и м е ч а н и е — Рисунки и таблицы в документе (частях документа) должны иметь индивидуальную нумерацию. Рисунки и таблицы должны нумероваться в порядке их расположения в документе (частях доку¬мента). Может быть использована единая, последовательная нумерация рисунков и таблиц.
8.2.3.3    Использование сносок или концевьх примечаний
Должны быть указаны возможности применения сносок или концевых примечаний.
П р и м е ч а н и е — В документации пользователя программного средства данные элементы обычно не используют; в спецификации стиля следует запретить их применение.
8.2.3.4    Правила пагинации и плотности документа
Должны быть определены правила пагинации (постраничного разбиения, например, чтобы заго¬ловки не проставлялись в конце страницы) и плотности документа (например, регулирование количе¬ства чистых страниц, начальных и концевых висячих строк).
8.2.3.5    Вводные и вспомогательные материалы
Должны быть определены виды вводных и вспомогательных материалов, включая (при необхо¬димости) требования к содержанию и оформлению:
a)    титульного листа;
b)    информации о гарантиях, авторских правах, компенсациях и торговой марке;
c)    содержания;
d)    списка рисунков и таблиц;
e)    приложений;
f)    словаря (глоссария);
g)    перечней обозначений и сокращений;
h)    указателя.
Должен быть определен порядок расположения данных элементов в документе.
П р и м е ч а н и е — Следует установить требования к содержанию и оформлению вводных и вспомога¬тельных материалов только необходимых видов.
8.2.3.6    Текст основной части документа
8.2.3.6.1    Гарнитуры и кегли шрифтов
Должны быть определены гарнитуры и кегли шрифтов, используемых в основной части доку¬мента.
8.2.3.6.2    Число колонок
Должно быть указано число колонок, используемых при оформлении страниц документа.
П р и м е ч а н и е — Наиболее часто в документации пользователя программного средства используют одноколонное оформление страниц, но может быть также использовано двухколонное оформление.
8.2.3.6.3    Отступы по горизонтали и пробелы по вертикали
Для текста основной части издания должны быть определены отступы (втяжки) слева или справа от края набора основного для издания формата, когда часть строк полосы набирают на более узкий формат со сдвигом влево (правосторонняя втяжка), вправо (левосторонняя), с обеих сторон (двусто¬ронняя), а также пробелы по вертикали (например, межстрочные, межабзацевые).
П р и м е ч а н и я
1    Для языков романской группы в тексте основной части документа следует избегать строк длиной более 65 и менее 30 символов.
2    Для подсчета соответствующей длины строки изначально выбирают строку длиной 5 см и считают количество символов (включая пробелы), содержащихся в десяти строках обычного текста (без разбивки на абзацы) данной длины. Полученное число делят на 50 для определения среднего числа символов на 1 см. Затем принимают решение о необходимом количестве символов в строке (которое должно быть между 30 и 65) и делят его на ранее определенное среднее число символов на 1 см для получения необходимой длины строки в сантиметрах.
8.2.3.6.4    Выравнивание
Должны быть определены параметры выравнивания текста основной части на выбранном языке (например, левостороннее или по ширине).
8.2.3.7    Заголовки
8.2.3.7.1    Количество уровней и наименования заголовков
Должно быть определено количество уровней заголовков, а для каждого уровня задано его обо¬значение или нумерация.
П р и м е ч а н и е — Следует избегать использования более трех уровней заголовков. Трех уровней обычно достаточно.
8.2.3.7.2    Стиль текста заголовков
Должен быть определен стиль текста заголовков для используемых в документации языков (на¬пример, «Стиль основных предложений», «Все буквы заглавные»).
8.2.3.7.3    Гарнитуры, кегли шрифтов и отступы для заголовков каждого уровня
Должны быть определены гарнитуры и кегли шрифтов, отступы по горизонтали и интервалы по вертикали для каждого уровня заголовков.
8.2.3.7.4    Графические элементы, используемые в заголовках
Должны быть определены графические элементы (например, подчеркивание, раскраска, пикто¬граммы), применяемые на каждом уровне заголовков.
8.2.3.8    Верхние и нижние колонтитулы
8.2.3.8.1 Содержание колонтитулов
Должно быть определено содержание заполнения верхних и нижних колонтитулов.
П р и м е ч а н и е — Например, таковыми могут быть номера страниц, проставляемые на полях.
8.2.3.8.2    Гарнитуры, кегли шрифтов и расположение колонтитулов
Должны быть определены гарнитуры и кегли шрифтов, а также горизонтальное и вертикальное расположение верхних и нижних колонтитулов. При двусторонней печати отдельно должно быть опре-делено содержание и оформление верхних и нижних колонтитулов левых и правых страниц.
П р и м е ч а н и е — Например, расположение номеров страниц на страницах каждого типа.
8.2.3.8.3    Используемые графические элементы
Должны быть определены графические элементы (например, подчеркивание, раскраска, пикто¬граммы), применяемые для колонтитула каждого типа.
8.2.3.9    Надписи
8.2.3.9.1    Содержимое
Должно быть определено содержимое надписей.
8.2.3.9.2    Гарнитуры, кегли шрифтов и расположение
Должны быть определены гарнитуры и кегли шрифтов, а также расположение надписей в доку¬менте.
8.2.3.10    Таблицы
8.2.3.10.1    Правила оформления
Должны быть определены правила оформления таблиц, например головки таблиц следует повто¬рять при переходе на другую страницу.
8.2.3.10.2    Гарнитуры и минимальные кегли шрифтов
Должны быть определены гарнитуры и минимальные кегли шрифтов, используемых в таблицах.
8.2.3.11    Отчеты (сообщения)
8.2.3.11.1. Общие положения
Отчеты (сообщения) являются результатами работы прикладных программных средств, выдавае¬мые в печатном или экранном виде. Образцы отчетов обычно включают в документацию пользователя программного средства.
8.2.3.11.2    Содержание
Могут быть установлены правила оформления и содержания отчетов.
П р и м е ч а н и е — Отчеты лучше понимаются, когда на каждом их поле распечатки экранов отражены реальные данные. В отчетах также должны быть использованы функциональные данные.
8.2.3.11.3    Гарнитуры и минимальные кегли шрифтов
Должны быть определены гарнитуры и минимальные кегли шрифтов, используемые в отчетах.
8.2.3.11.4    Использование горизонтальной компоновки и страниц-раскладок
Должны быть определены правила по использованию горизонтальной компоновки (то есть аль¬бомных форматов) для очень широких или длинных отчетов. Должны быть также установлены правила использования в отчетах страниц-раскладок и страниц-разверток.
8.2.3.12    Распечатки экранов
8.2.3.12.1    Содержание
Должны быть установлены общие правила содержания распечаток экранов.
П р и м е ч а н и е — Распечатки экранов лучше понимаются, когда на каждой из них отражены реальные данные. В распечатках также должны быть использованы функциональные данные.
8.2.3.12.2    Оформление (компоновка)
Должны быть установлены общие правила оформления (компоновки) распечаток экранов.
8.2.3.12.3    Оформление частичных распечаток экранов
Должны быть установлены (при необходимости) правила оформления частичных (неполных) распечаток экранов.
8.2.3.13    Рисунки
8.2.3.13.1    Минимальная толщина линий, гарнитуры и кегли шрифтов
Должны быть установлены, используемые в рисунках гарнитуры и кегли шрифтов, а также минимальная толщина линий.
8.2.3.13.2    Расположение
Должны быть установлены правила расположения (ориентации) рисунков.
8.2.3.14    Уведомления и предостережения
8.2.3.14.1    Стиль текста
Должен быть определен стиль текста уведомлений и предостережений для используемых в доку-ментации языков (например, «Стиль основных предложений», «Все буквы заглавные»).
8.2.3.14.2    Гарнитуры, кегли шрифтов и отступы
Должны быть определены гарнитуры и кегли шрифтов, отступы по горизонтали и интервалы по вертикали для уведомлений и предостережений.
8.2.3.14.3    Графические элементы, используемые в заголовках
Должны быть определены графические элементы (например, подчеркивание, раскраска, пикто¬граммы), используемые в уведомлениях и предостережениях.
8.2.4 Э л е к т р о н н а я д о к у м е н т а ц и я
8.2.4.1    Типы справочной информации
В спецификации стиля документации могут быть указаны один или несколько из следующих типов справочной информации:
a)    контекстная справка (context help) — информация о текущем поле, в котором находится курсор или высвечена программа, включая ее необходимое или целевое (предметное) содержание, ее назначение и потенциальное влияние на работу программного средства;
b)    расширенная справка (extended help) — информация о текущем экране или окне, включая ее назначение и требуемый режим использования;
c)    справка о клавишах (keys help) — информация о применении клавиатуры, функциональном назначении клавиш и их перенаименовании (обозначении);
d)    справка о справках (help to help) — информация об использовании справочной системы в целом;
e)    справка о сообщении (message help) — информация о том, что пользователь должен или может сделать в ответ на конкретные системные сообщения, например сообщения об ошибках;
f)    терминологическая справка (reference phrase help) — определения конкретных элементов, связей с конкретной тематикой и расшифровка обозначений и сокращений;
g)    понятийная справка (intelligent help) — справочная информация, выдаваемая системой для предупреждения пользователя об ошибках. Может быть структурирована, чтобы первоначально пользо¬ватель получал краткое справочное сообщение, а при повторении той же ошибки — более подробное сообщение, и наоборот, пользователь может получить развернутое сообщение при первой ошибке и краткое — при ее повторении.
8.2.4.2    Типы диалоговой (оперативной) документации
В спецификации стиля электронной документации могут быть указаны один или несколько из следующих типов диалоговой документации:
a)    руководства или рекомендации пользователя (user guide or reference) — описывают процедуры по применению продукта;
b)    командные справки (command reference) — определяют синтаксис, результаты и целевое назна¬чение каждой команды (только для команд управления системой);
c)    рекомендации по сообщению (message reference) — определяют, что пользователь должен или может сделать в ответ на конкретные системные сообщения, например сообщения об ошибках;
d)    административная информация (administration information) — информация о конфигурации и защите системы, а при необходимости — о ее инсталляции, предназначенная для администратора системы.
8.2.4.3    Оформление
8.2.4.3.1    Общее положение
Оформление (компоновка) информации в системах справочной и диалоговой (оперативной) документации во многом может определяться возможностями инструментальных средств, используе¬мых при их создании.
8.2.4.3.2    Сопутствующие материалы
Должны быть установлены правила размещения материалов, связанных с электронной докумен¬тацией, и их местоположение.
8.2.4.3.3    Подсветка и использование цвета
Должны быть установлены правила использования в электронной документации подсветок выде-ляемых элементов и использование цветового оформления.
П р и м е ч а н и я
1    Использование подсветок и цветов для выделения элементов документации должно быть миниминизи- ровано, особенно в случае возможной путаницы между выделенным текстом и гипертекстовыми связями.
2    Цвета следует использовать осторожно, особенно при отсутствии уверенности в том, что тот же цвет не используется для уведомления о более важной информации. Это особенно важно при наличии у пользова¬телей возможностей выбора различного цветового оформления экранов.
3    Для четкого выделения элементов и во избежание возникновения при этом проблем по возможности следует основные цвета (красный, зеленый и синий) использовать на фоне белого или черного.
4    Различные яркие цвета не следует использовать последовательно, так как это может привести к воз-никновению на экране трехмерных эффектов.
5    Обычно некоторые цвета имеют определенные смысловые значения (например, красный — «стой» или «опасно», зеленый — «продолжить» или «безопасно») и могут быть выбраны соответственно этому значе¬нию. Данный тип цветосочетания следует использовать осторожно, если пользователи могут выбирать различ¬ные цветовые оформления экранов.
6    Колористика экранов дисплеев является сложным вопросом и часто связана с недостаточной проект¬ной проработкой. Документаторам в этом случае следует обращаться за помощью к соответствующим специ¬алистам.
8.2.4.3.4    Оформление диалоговой документации и справочного текста
Должны быть установлены правила оформления соответствующих текстов.
8.2.4.3.5    Заголовки
Должны быть установлены правила оформления соответствующих заголовков.
8.2.4.3.6    Текст основной части
Для текста основной части электронной документации должны быть определены следующие элементы:
a)    выравнивание (для соответствующих языков);
b)    отступы и интервалы.
П р и м е ч а н и е — Для языков романской группы следует избегать строк длиной более 65 и менее 30 символов. Интервал между строками следует устанавливать не менее двух пикселей или 15 % от высоты симво¬ла, независимо от его величины. Это не распространяется на знаки ударения или выносные элементы строч¬ных символов;
c)    минимальная высота символа.
П р и м е ч а н и е — Для языков романской группы высота символов должна быть не менее 16 и не более 45 угловых минут. Предпочтительной высотой символа являются 20—22 угловые минуты. Угловые минуты ис-пользуются в качестве показателя высоты символа на видеодисплее; данный показатель отражает охват симво¬ла глазом. Он зависит не только от фактической высоты символа на экране, но также от нормального расстояния до экрана. В таблице 1 показано отношение между высотой символа в угловых минутах и миллимет¬рах на расстоянии в 1 м. Например, на более коротком расстоянии высота пропорционально уменьшается по сравнению с заданной в таблице. В таблице для сравнения также показано соответствующее число отображае¬мых точек для гарнитуры «Times Roman».
Т а б л и ц а 1 — Угол обзора и число точек
Угол обзора, угловые минуты    Высота, мм    Приблизительное число точек
10    2,9    12
15    4,4    18
20    5,8    24
25    7,3    30
30    8,8    36
35    10,2    42
40    11,6    48
45    13,1    54
50    14,6    60

8.2.4.3.7    Навигация
Должны быть установлены правила навигации по электронной документации.
П р и м е ч а н и я
1    Уровни связей информации в документации должны контролироваться, обеспечивая пользователю возможности возврата в исходный пункт, содержание или указатель без блуждания в документе.
2    Должны быть выработаны и применены правила структурирования документа. Например, количество связей в каждой информационной цепочке должно быть ограничено числом X Значение Xдолжно быть таким, чтобы пользователи имели соответствующие возможности для возврата к содержанию или перехода к другим структурным элементам документа. Уровни заголовков также могут быть взаимоувязаны с уровнями сложно¬сти документа (например, «В заголовках первого уровня представляется только общая информация»).
3    Проблемно ориентированная и общая информация должны быть выделены в отдельные разделы с входящими связями между ними, тем самым позволяя пользователю изучить конкретную задачу без непред-намеренного поиска в общих материалах, что может дезориентировать и отвлекать его.
4    Следует использовать графические материалы. Общая схема, отражающая основные разделы докумен¬та с гипертекстовыми связями между ними, дает пользователю ясное визуальное представление о структуре документа.
5    В начале документа должен быть раздел с рекомендациями пользователю, содержащий информацию по применению диалоговой документации. Данный раздел следует использовать для пояснения структуры до¬кумента и правил по его применению.
8.2.4.3.8    Использование клавиатуры
Должны быть определены правила использования специальных клавиш в диалоговой документа¬ции.
П р и м е ч а н и я
1    Пользователь должен иметь возможность вызова справки, используя конкретную клавишу или комби¬нацию клавиш, в любой точке программы. Пользователь также должен иметь возможность вызова диалоговой документации с использованием единственной клавиши или комбинации клавиш.
2    В плане документирования должны быть определены условные наименования и функции всех специ¬альных функциональных клавиш, используемых в системе диалоговой или справочной документации.
3    Применение специальной функциональной клавиши в документации должно быть соотнесено с ис-пользованием функциональных клавиш в самом программном приложении.
Перекрестные ссылки с ГОСТ Р ИСО/МЭК 12207
Настоящий стандарт соответствует ГОСТ Р ИСО/МЭК 12207 в части реализации его подраздела 6.1 по отношению к документации пользователя (см. таблицу А.1).
Т а б л и ц а А.1 — Перекрестные ссылки с ГОСТ Р ИСО/МЭК 12207
Пункты ГОСТ Р ИСО/МЭК 12207    Пункты настоящего стандарта
6.1.1.1    8.1.3 План документирования
6.1.2.1    8.2 Содержание спецификации стиля
6.1.2.2    8.1.2 Представление исходных материалов
6.1.2.3    8.1.4 Проверка (анализ)
6.1.3.1    8.2 Содержание спецификации стиля. 8.1.3 План документиро-вания
6.1.3.2    8.1.3.3 Проверка плана документирования
6.1.4.1    8.1.7 Контроль изменений и сопровождение документации

ПРИЛОЖЕНИЕ В (справочное)
Использование настоящего стандарта в договоре
В.1 Общие положения
В настоящем стандарте имеются разделы, требования которых необходимо пояснить применительно к конкретному договору или другим ссылочным документам (например, международным). В свою очередь, план документирования также нуждается в пояснении. В договоре должны быть даны ответы на следующие вопросы:
a)    откуда поступает информация о изучении аудитории? (Ответ рекомендуемый);
b)    необходимо ли готовить более двух проектов комплекта документации и одного комплекта гранок? (При необходимости, в настоящем стандарте по умолчанию предусмотрены два проекта комплектов доку¬ментации и один комплект гранок);
c)    кто представляет исходные материалы? (Обычно это очевидно, но для проектов со сложными взаи-мосвязями между вовлеченными сторонами нуждается в уточнении);
d)    какие уровни конфиденциальности или секретности необходимо использовать для материалов, пре-доставляемых заказчиком документатору?
e)    имеется ли стандарт на оформление бумажной документации? (Это не обязательно; по умолчанию может быть использована спецификация стиля документации, установленная в настоящем стандарте; затем в плане документирования может быть оговорено количество проектов документации и т. д.).
В.2 Образец раздела договора
В соответствии с настоящим стандартом образец раздела договора может быть представлен в следующем
виде.
П р и м е р
Раздел 123 Документация
Вся документация пользователя должна соответствовать ГОСТ Р ИСО/МЭК 15910.
В комплект документации не следует включать диалоговую документацию и справочные тексты. Вся информация об изучении аудитории и другие исходные материалы должны представляться заказчиком.
Должно быть проведено одно тестирование на практичность при поставке первого модуля программно¬го средства, которое должно предусматривать проверки всех функциональных возможностей данного модуля в интересах пяти различных типовых пользователей.
В.3 Практическое применение настоящего стандарта
Необходима адаптация настоящего стандарта в интересах потребителей и пользователей в целях его практического применения.
Практическое применение настоящего стандарта обычно заключается в исключении и добавлении ряда разделов, что должно быть оговорено соответствующим соглашением (как правило, в договоре, но возможно и в плане документирования).
Практическое применение настоящего стандарта следует проводить тщательно, с учетом его общей структуры.
ПРИЛОЖЕНИЕ С (справочное)
Образец плана документирования. Документация пользователя для системы АВС — административного управления магнитными лентами
С.1 Введение
В настоящем плане описана стратегия разработки документации пользователя для системы АВС, пред-ставляемой в виде комплекта документации XYZ. Определена область применения проекта, номенклатура поставки документации и ресурсы, необходимые для ее создания.
Данная стратегия предусматривает создание твердых копий документации и диалоговой документации в виде справочных текстов.
В случае изменения данной стратегии следует пересмотреть план документирования.
С.2 Область применения и ограничения
В комплекте документации не предусмотрены инструкции по применению операционной системы, на которой прогоняется система АВС. Однако для читателя должны быть указаны ссылки на соответствующие руководства по данному вопросу.
Инсталляция, ввод в действие и управление документацией системы АВС уже реализованы и не рассмат-риваются в настоящем проекте.
С.3 Оформление и стиль описания
По умолчанию следует использовать оформление и стиль описания, указанные в ГОСТ Р ИСО/МЭК 15910. Образец страницы приложен к плану документирования.
Т а б л и ц а С.1 — Руководство по стилю
Элемент    Значение
Содержание справочного текста    Должен быть описан только контекст справки
Содержание диалоговой документации    Отсутствует
Сопутствующие материалы    Справочный текст для каждого объекта должен быть представлен на одном экране
Засветки и использование цветов    В справочном тексте не следует использовать цвета и другие засветки
Оформление диалоговой документации и справоч¬ного текста    Должен быть использован одноколонный формат

Окончание таблицы С.1
Элемент    Значение
Оформление заголовков диалоговой документации и справочного текста    Вверху каждой страницы справочного текста должен быть проставлен заголовок первого уровня: кегль 14 п, гарнитура Times Roman
Оформление основной части документа    Текст должен быть выровнен по левому краю и на¬бран одним шрифтом
Правила навигации    В соответствии со справочным механизмом системы АВС
Использование клавиатуры    В соответствии со стандартами на систему АВС
С.4 Аудитория

В аудиторию пользователей данной системы входят операторы компьютеров, обладающие минимальны¬ми техническими знаниями. Минимальное образование операторов должно соответствовать 12-летнему сред¬нему (школьному) образованию.
Аудитория не охватывает безграмотных пользователей; все пользователи должны обладать хорошими навыками чтения.
Пользователи должны иметь однолетний (двухлетний) опыт работы в качестве операторов вычисли¬тельного центра, включая навыки по эксплуатационным процедурам запуска, остановки, резервирования и сохранения систем, а также загрузки и разгрузки магнитных лент. В их обязанности также должен входить контроль диагностических сообщений от системы и реакция на них.
Предполагается, что пользователи:
a)    понимают общие процедуры управления магнитными лентами;
b)    обладают адекватным восприятием соответствующих команд операционной системы;
c)    не имеют навыков работы с магнитными лентами в системе АВС.
С.5 Проект содержания документации
Содержание включает в себя следующее:
a)    введение — концепция АВС и ее связь с системой (пять страниц);
b)    обзор — общие функции системы АВС (три страницы);
c)    установка ленты (пять страниц);
d)    снятие ленты (пять страниц);
e)    проблемы — руководство по определению дефектов, включая системные сообщения (четыре страницы);
f)    словарь терминов и определений (одна страница);
g)    указатель (одна страница).
Всего 24 страницы.
С.6 Номенклатура поставки
По окончании проекта должны быть поставлены следующие объекты:
a)    500 переплетенных копий руководства;
b)    электронная копия всей документации на дискетах емкостью 1,44 Мбайт, диаметром 3,5 дюйма в формате DEF 3.0 (пригодная для распечатки документации на принтере);
c)    электронная копия справочного текста.
С.7 Авторские права
Авторские права на все материалы принадлежат организации XYZ.
С.8 Транспортирование
Особых условий по транспортированию продукции не требуется.
С.9 Процесс разработки и контроль
При создании руководств пользователя системы АВС должны использоваться процедуры разработки и контроля, установленные в Руководстве по качеству организации XYZ.
С.10 Тиражирование
При производстве руководств пользователя системы АВС следует использовать типографскую систему DEF (версия 3.0). Графические материалы следует разрабатывать с использованием графического пакета JKL.
Виды экранов дисплея для системы АВС следует собрать в электронном виде, а их копии — внести в окончательный документ.
Содержание и указатель должны быть подготовлены и выпущены на системе DEF.
Копии фотошаблонов должны быть отпечатаны на лазерном принтере с плотностью печати 300 точек на дюйм; за отдельную плату они могут быть распечатаны на лазерном принтере высокого качества с плотно¬стью печати 1275 точек на дюйм.
Каждое руководство должно быть выполнено в формате А4 с двусторонней печатью и сброшюровано так, чтобы была возможность заменять листы.
Переплет должен быть формата А4 и скреплен кольцами диаметром 25 мм. На обложке должны быть приведены распечатки экранов системы АВС.
Бумага для руководств должна быть матовой и иметь плотность 103 г/см2.
Справочные тексты должны быть разработаны с использованием макетирования в системе DEF.
С.11 Проектанты
Состав коллектива разработчиков и их обязанности приведены в таблице С.2. Т а б л и ц а С.2 — Проектанты
Фамилия, имя    Роль    Обязанность
О’Брайен П.    Автор    Изучение плана и написание руководств
Коста А.    Редактор    Редактирование руководств
Ричардс Р.    Нормоконтролер    Проверка технического содержания руководств
Джонс Е.    Технический аудитор    Проведение технических проверок и выдача рекомендаций
Вонг С.    Разработчик    Набор текста и подготовка графических материалов
Келли А.    Ответственный за качество    Управление качеством
Даунс М.    Ответственный за тестирование    Тестирование готового руководства при определенных усло-виях и подготовка отчета о результатах тестирования

С.12 Ресурсы
Информацию, необходимую для разработки руководств, следует выбирать из проектной документации на систему АВС, получать от разработчиков программных средств и отбирать по результатам опытной эксплу¬атации данной системы.
Разработчикам документации необходимы следующие ресурсы:
a)    копии функциональной проектной документации на систему АВС;
b)    доступ к системе АВС;
c)    доступ к разработчикам программного обеспечения системы АВС.
С.13 Тестирование на практичность
После корректировки второго проекта документации по замечаниям заказчика должно быть проведено тестирование на практичность руководства пользователя и справочных текстов для системы АВС.
Целью тестирования является оценка степени, в которой язык, содержание и оформление руководства пользователя и справочных текстов для системы АВС облегчают пользователям практическое применение программных средств данной системы.
Тестирование должно проводиться в машинном зале с использованием бета-версии тестов для АВС; в тестировании должно участвовать по одному представителю от разработчиков программных средств и разра-ботчиков документации (далее — представители).
Тестирование должно проводиться с привлечением четырех типовых пользователей, перечисленных в С.4, выбранных произвольно из персонала ночной смены, эксплуатирующего систему. Каждому из них долж¬ны быть даны копии руководства пользователя и справочных текстов для системы АВС с просьбой выполнить ряд действий (перечисленных в плане тестирования).
Представители записывают время выполнения каждого действия, замечания пользователя и процессы, выполняемые пользователями при реализации каждого действия.
При превышении любым пользователем времени выполнения действия, указанного в плане тестирова¬ния, или неправильном выполнении данного действия представители записывают соответствующие замеча¬ния пользователя о причинах возникшей проблемы.
Эти замечания представляются на совещании по рассмотрению документации и в качестве изменений в проект документации. На совещании определяют целесообразность проведения повторного тестирования.
С.14 График работ
График работ показан в таблице С.3.
Т а б л и ц а С.3 — График работ
Этап    Срок    Отношения
Представление первого проекта    01.01.99    План документирования утвержден 15.12.98
Представление второго проекта    15.02.99    Три недели на проверку первого проекта
Тестирование на практичность    15.03.99
Представления справочных тек¬стов    15.04.99    Тестирование на практичность
Представление гранок    15.04.99    Тестирование на практичность; две недели на проверку второго проекта
Подготовка фотошаблонов    30.04.99    Тестирование на практичность
Распечатка и брошюровка    15.05.99    Наличие переплетенных томов

ПРИЛОЖЕНИЕ D (справочное)
Отношения между аудиториями, выданными заданиями, бумажной и диалоговой документацией
Проектирование документации начинается с анализа пользователей документируемой системы. Как пра¬вило, существуют определенные группы пользователей, объединяемые в определенные аудитории в соответ¬ствии с их потребностями.
В ряде случаев иерархию аудиторий целесообразно представлять в виде отдельных групп, как показано на рисунке D.1.

Рисунок D.1 — Иерархия аудиторий

Рисунок D.2 — Иерархия заданий

На следующем этапе для определенной аудитории в рамках выданных ей заданий определяют перечень ее потребностей в информации (information needs). На основе данного перечня определяют содержание конкрет¬ного документа, как показано на рисунке 3.

Рисунок D.3 — Информационные потребности
На данном этапе (но не ранее) следует определить вид (тип) конкретного документа и машинный носитель, на котором он поставляется.
Например, информационные потребности данной аудитории в рамках конкретного задания могут быть удовлетворены в формате печатного руководства, диалогового руководства, контекстно-зависимых справоч¬ных экранов, справочных схем или видео- и оперативных руководств.
Обычно стремятся сократить номенклатуру разрабатываемых документов. При этом стараются один документ использовать в разных целях.
На рисунке D.4 показаны виды деятельности (работы), выполняемые в процессе проектирования доку-ментации. Одним из важных моментов является представление пользователю необходимых сведений на раз¬личных носителях; потребность в этом не предопределяется ролью диалоговой или бумажной документации; ролью любого носителя является представление пользователю необходимых сведений в требуемом виде (фор¬мате) в зависимости от конкретной аудитории, продукта и набора заданий пользователя. Планирование доку¬ментации (в соответствии с настоящим стандартом) связано только с установлением набора сведений, необ¬ходимых пользователям, и лишь в конце процесса документирования решается вопрос о выборе носителя, на котором следует представлять эти сведения. Например, диалоговую и бумажную документацию следует плани¬ровать одновременно, так как одному пользователю для получения необходимых сведений может потребо¬ваться документация обоих видов.

Рисунок D.4 — Общая структура процесса проектирования документирования Более подробное описание процесса проектирования документации приведено в BS 7649—93 [2].
Рекомендации по написанию на английском языке документации, подлежащей последующему переводу
Е.1 Общие положения
В настоящем приложении приведены рекомендации, которые следует учитывать при написании на английском языке исходных материалов, подлежащих последующему переводу на другие языки. Большая часть данных рекомендаций относится как к бумажной, так и диалоговой документации.
Е.2 Терминология
В части терминологии, используемой в документах, необходимо руководствоваться следующими прави¬лами:
a)    применять общие и нетехнические термины в соответствии с их определениями, установленными в общих словарях;
b)    создавать глоссарии (словники), содержащие:
1)    определения всех специфических и неизвестных терминов,
2)    виды и определения всех обозначений и сокращений,
3)    толкования непривычного использования слов, применение имен существительных в качестве наречий,
4)    библиографию специализированных словарей и стандартов;
c)    специальная терминология должна быть основана на национальных или международных терминоло-гических стандартах, общепризнанных словарях или согласованных глоссариях;
d)    каждое сокращение должно быть расшифровано при первом его появлении в тексте основной части документа;
e)    каждый термин должен одинаково трактоваться в документе, диалоговой информации и системной библиотеке;
f)    составные выражения (например, «ввод данных [data input]») должны иметь одно смысловое значение во всей документации;
g)    составные выражения не должны содержать более трех слов;
h)    одно и то же слово не должно использоваться для различных частей речи;
i)    все специфические и специальные термины должны использоваться в соответствующем контексте; j) термины, вводимые вне соответствующего контекста, например наименования клавиш или коман¬ды, должны быть определены в глоссарии;
k) следует избегать использования термина «биллион (billion)».
П р и м е ч а н и е — Американский биллион (109) не совпадает с английским биллионом (1012);
1) следует избегать использования термина «перевод (translation)», например при ссылке на перевод в формат файла, в смысловом значении, отличном от перевода с одного языка на другой. Вместо этого следует применять термин «преобразование (со^еЛю^)».
Е.3 Стиль перевода
Е.3.1 О б о з н а ч е н и я
Следует использовать только общепринятые обозначения, которые должны быть расшифрованы в спис¬ке обозначений. Не должны применяться следующие обозначения:
a)    американский символ «#» для фунта;
b)    приподнятая точка (•) для операции умножения. Е.3.2 Н е о д н о з н а ч н о т р а к т у е м ы е с л о в а
Авторы документов должны избегать использования следующих неоднозначно трактуемых слов:
a)    who (кто), that (который), which (какой);
b)    only (только), merely (приблизительно), just (едва), mainly (в основном), simply (просто);
c)    while (пока);
d)    so (таким образом);
e)    as (как);
f)    can (иметь возможность), may (мочь);
g)    since (так как);
h)    when (когда), if (если);
i)    alternate (дополнительный), alternative (альтернативный).
Е.3.3 С и н т а к с и с
Должны быть учтены следующие вопросы синтаксиса:
a)    предложения не должны быть слишком длинными;
b)    следует избегать построения предложений, описывающих ряд положений, разделяемых чрезмерным количеством запятых;
c)    пункты, содержащие определенные ограничения, и пункты без ограничений должны быть представ¬лены раздельно.
Е.3.4 П у н к т у а ц и я
Там, где могут быть использованы скобки или точка с запятой, не следует применять тире.
Е.4 Физические факторы
Необходимо учитывать следующие физические факторы:
a)    сокращения нецелесообразно использовать только для экономии места;
b)    предусмотреть необходимые места для простановки соответствующих значений, например цены;
c)    следует использовать стандартные графические инструментальные средства (пакеты) и избегать при-менения вклеек;
d)    избегать внесения поясняющего текста в рисунки;
e)    следует использовать графические символы, имеющие общепринятое смысловое значение;
f)    по возможности вместо словесного пояснения использовать графические изображения.
Е.5 Диалоговая информация
Применительно к диалоговой информации необходимо учитывать следующие положения:
a)    при наличии обратной связи с разработчиками программных средств следует обеспечить выделение диалоговой информации (текстов и сообщений) из логики программы;
b)    каждый блок текста или сообщение должны иметь индивидуальное идентификационное обозначение с указанием соответствующей классификационной группы данного текста или сообщения;
c)    конкретное программное средство не должно ориентироваться на длину, формат или расположение незащищенных экранных полей ввода—вывода (input and output fields);
d)    для каждого понятия следует использовать отдельное сообщение. Сообщения не должны быть наду-манными;
e)    переменные в сообщении должны содержать только непереводимую информацию, например ключе¬вые слова и коды возврата;
f)    из предложений не следует исключать предлоги в целях экономии места.
Е.6 Культурные факторы
Применительно к культурным факторам необходимо учитывать следующие положения:
a)    иллюстративные материалы (например, лица, животные и звуки речи) должны быть независимыми от национальных культурных особенностей;
b)    следует избегать использования примеров, связанных со специфическими национальными традиция¬ми или особенностями (например, праздниками, банковским делом, зарплатой, спортом и т. д.);
c)    в тексте и иллюстрациях следует избегать использования идиоматических выражений, присущих наци-ональному языку документатора;
d)    следует избегать использования юмористических выражений, особенно каламбуров.
e)    следует осторожно использовать иронические выражения;
f)    необходимо избегать использования сленговых, жаргонных и простонародных выражений;
g)    не должны использоваться упоминания первых лиц государства;
h)    не следует выражать даты только в числовом виде. Месяц всегда должен быть написан полностью (например, 28 июля 1991);
i)    обычно следует использовать двумерные представления, если международные соглашения не требу¬ют иного (например, для автошин, водопроводов, гвоздей и фотопленки);
j) когда метрические величины располагаются вместе с величинами в других системах измерения, из контекста должно быть понятно, какая из величин относится к соответствующей системе измерений.
Оценка проекта
F.1 Общие положения
В настоящем приложении представлен ряд рекомендуемых методов оценки проекта. В ряде случаев эти методы противоречат друг другу, так как оценка проекта документирования достаточно субъективна. В частно¬сти, данные оценки могут быть завышенными при внесении изменений в программное средство в процессе его документирования.
Данные методы позволяют сделать практические прикидки, на фактические сроки реализации проекта следует проставлять исходя из практического опыта экспертов, проводящих соответствующие оценки.
F.2 Поминутный и почасовой методы
Данные методы предусматривают около 3 ч для написания страницы текста, пригодного для публикации. Время, необходимое для создания графических материалов, определяется их сложностью и количеством чер-новиков, необходимых для создания соответствующего оригинала.
По общей оценке требуется от 3 до 5 ч для создания и корректировки типового графического материала, используемого в программной документации (исключая экранные распечатки).
В начале проекта трудно оценить общий постраничный объем создаваемой документации. Если для завер-шения проекта требуется более 2 мес, подсчет страниц должен быть проведен по истечении первого месяца.
Для очень больших проектов номенклатура поставки должна быть разделена на части, поддающиеся управлению. При этом оценка сроков завершения проекта в целом может быть дана только в количестве месяцев, а детально может быть оценена лишь первая часть работы. При использовании данного метода доку¬ментатор и заказчик должны сверить свои оценки сроков завершения проекта.
В таблице F.1 приведены сроки реализации «типового» (гипотетического) проекта. При этом предпо¬лагается, что автор готовит материалы непосредственно на персональном компьютере, и для их выпуска используют портативные издательские системы.
Т а б л и ц а F.1 — Ориентировочные сроки
Этап    Срок
Определение номенклатуры поставки    16 ч на проект
Исследование содержания документации    24 ч на проект
Написание плана документирования    48 ч на проект
Проектирование структуры документа и правил оформления его страниц    8 ч на том
Написание первой редакции (документации)    1 ч на страницу
Разработка графических материалов    5 ч на материал
Объединение текстовых и графических материалов    30 мин на страницу
Проверка первой редакции (эксперт)    30 мин на страницу
Корректировка первой редакции и графики    30 мин на страницу
Внесение замечаний пользователя    30 мин на страницу
Грамматическое редактирование    15 мин на страницу
Подготовка второй редакции (документации)    15 мин на страницу
Проверка второй редакции (эксперт)    15 мин на страницу
Окончательная корректировка документации    10 мин на страницу
Нормоконтроль документации    15 мин на страницу
Изготовление фотошаблонов    3 сут
Печать и переплетение оригиналов    5 сут
Печать и брошюровка копий    10 сут
Рассылка    1 сут

F.3 Метод нисходящего проектирования
F.3.1 О б щ и е п о л о ж е н и я
Данный метод основан на предположении, что число страниц в публикации(ях) может быть оценено достаточно просто с использованием следующих допущений:
a)    автор может за месяц подготовить 22 страницы нового текста;
b)    автор может за месяц подготовить 44 страницы текста с изменениями.
Например, объем публикации оценен в 150 страниц. Поскольку это новая публикация, получаем: 150/22 = 7 чел./мес. В эти 7 мес входят: планирование публикации, ее написание, редактирование и проверка двух редакций, а также подготовка фотошаблонов. F.3.2 П р о п о р ц и и
Продолжительность 7 чел./мес распределена в следующих пропорциональных отношениях:
a)    15 % — планирование (в данном примере — четыре недели);
b)    50 % — написание первой редакции (14 недель);
c)    25 % — написание второй редакции (семь недель);
d)    10 % — подготовка фотошаблонов (три недели). F.3.3 П л а н и р о в а н и е
Период планирования охватывает:
a)    исследования и подготовку плана;
b)    изучение и проверку плана;
c)    корректировку плана по результатам проверки. F.3.4 П е р в а я р е д а к ц и я
Период первой редакции охватывает:
подготовку содержания (плана-проспекта) документации;
изучение и проверку содержания (плана-проспекта);
подготовку пробного куска текста для редактора;
редактирование пробного куска текста и его переписывание по замечаниям редактора;
написание всей первой редакции документации;
редактирование всей первой редакции документации;
переработку отредактированной документации;
изучение и проверку переработанной документации.
Иллюстративные материалы готовят одновременно с текстом первой редакции. F.3.5 В т о р а я р е д а к ц и я Период второй редакции охватывает:
a)    внесение в документацию всех изменений, предложенных по результатам проверки первой редакции;
b)    повторное (второе) редактирование второй редакции документации;
c)    переработку отредактированной документации;
d)    изучение и проверку переработанной документации. F.3.6 П р и н я т а я р е д а к ц и я
Редакцией для фотонабора является принятая редакция документирования. Ее подготовка охватывает:
a)    внесение в документацию всех изменений, предложенных по результатам проверки второй редакции;
b)    проверку правильности внесения данных изменений;
c)    удаление всех редакционных разметок;
d)    изготовление фотошаблонов;
e)    отправку фотошаблонов в печать (в типографию).
Обычно экспертам (нормоконтролерам) требуется от одной до двух недель для изучения и подготовки замечаний, а сама проверка занимает от одного до нескольких дней.
Метод нисходящего проектирования может быть использован для существующих публикаций. Напри¬мер, книга объемом 100 страниц может быть переработана так, что половина ее изменяется и добавляется 10 % новых материалов. Используя вышепринятые допущения, получаем: 50/44 = 1,13 чел./мес для существую¬щего материала плюс 10/22 = 0,45 чел./мес для внесения нового материала.
Когда сроки, необходимые для создания документации, превышают допустимые, для выполнения зада¬ния следует привлекать несколько авторов. Так же следует поступать при подготовке нескольких документов для одного программного средства.
Оценка плана документирования
Использование настоящего стандарта во взаимоотношениях между заказчиком и документатором спо-собствует созданию качественной документации в частности потому, что между ними согласовывается план документирования. Этим достигается двойной эффект: во-первых, документатор учитывает все аспекты доку-ментации, оговоренные в плане; во-вторых, заказчик и документатор согласуют метод документирования, определенный в плане, еще до начала работы.
Заказчик должен установить наличие в плане документирования следующих элементов:
a)    соответствующих определений всех аудиторий. Формулировка вида «Руководство предназначено для аудитории, охватывающей пользователей программного средства» неполна (см. приложение D). В определение аудитории должны быть включены все лица, могущие использовать данное программное средство (включая лиц, которые могут только просматривать отчеты или сообщения от данного средства);
b)    содержания (планов-проспектов) документации с оценкой их постраничного объема;
c)    определения числа печатных копий и методов печати (тиражирования) и брошюровки документации;
d)    однозначного определения собственника авторских прав на документацию;
e)    установление методов подготовки документации. Большинство технических документов может быть создано при помощи компьютера;
f)    достаточных сроков для проверки заказчиком редакций документации. Любые отсрочки при возврате документатору проверенных редакций могут привести к срыву сроков поставки документации;
g)    от организации-заказчика может потребоваться обеспечение документатора соответствующими ресур-сами (доступом к ее персоналу, оборудованием и т. д.), при отсутствии которых работы могут быть сорваны.
В целом план документирования должен учитывать все специфические обстоятельства, относящиеся к организации-заказчику и пользователям. Крайне маловероятна возможность использования плана документи-рования, разработанного в рамках одного проекта, для другого.
ПРИЛОЖЕНИЕ Н (справочное)
Образец спецификации стиля
Н.1 Общие положения
Представленный образец спецификации стиля документации соответствует требованиям 8.2 и по умол¬чанию может быть использован в плане документирования.
П р и м е ч а н и е — Перед окончательным принятием данной спецификации полезно создать на ее основе модель документа.
Н.2 Элементы стиля
В таблице Н.1 приведены элементы стиля и их рекомендуемые значения по умолчанию.
Т а б л и ц а Н.1 — Элементы стиля и их значения
Элемент    Значение
Язык    Английский
Орфографический словарь    Словарь Маквайра
Руководство по грамматике и использова¬нию стиля    «Руководство по стилю для авторов, редакторов и издателей» Австралийское государственное издательство

Продолжение таблицы Н. 1
Элемент    Значение
Формат бумаги    А4
Ориентация    Книжная (вертикальная)
Вид печати    Двусторонняя
Разрешающая способность типографской или лазерной печати    Минимум 300 точек/дюйм
Ширина внутреннего поля    10 мм/2,4 цицеро*
Ширина внешнего поля    10 мм/2,4 цицеро*
Цвет краски    Черный
Цвет, масса и вид бумаги    Белая, 80 г/см2, матовая
Разделители    Нет
Переплет    Пластиковый комбинированный, с прозрачной верхней и чер¬ной нижней обложками, плотностью 200—260 г/см2
Метод воспроизведения и качество    Все материалы должны быть пригодными к фотокопированию и не иметь помарок и обесцвечиваний
Схема нумерации страниц    Страницы нумеруют в формате 1, 2, 3 и т. д., начиная с первой после обложки
Нумерация таблиц и рисунков    Рисунки нумеруют в формате «Рисунок 1», «Рисунок 2» и т. д., в порядке их появления в тексте документа. Таблицы нуме¬руют в формате «Таблица 1», «Таблица 2» и т. д., в порядке их появления в тексте документа
Число колонок    Одна
Сноски или концевые примечания    Не используют
Правила пагинации    Заголовки не должны попадать в конец страницы. Таблицы объе-мом менее страницы должны размещаться на одной странице. Каждый заголовок первого уровня должен располагаться вверху правой страницы
Правила плотности документа    Взаимосвязанные материалы следует размещать на одной стра-нице или на ее обороте. Следует по возможности избегать ис-пользования подчеркивания, больших кусков, набранных жир¬ным шрифтом, и текстов, целиком набранных заглавными буквами.
Материалы должны занимать от 40 % до 60 % общего объема страницы
Вводные и вспомогательные материалы: – титульный лист    На титульном листе должно быть указано наименование про-дукции, ее версия, дата выпуска документа и название данно¬го тома

Продолжение таблицы Н.1
Элемент    Значение
–    информация о гарантиях, авторских пра-вах и торговой марке
–    содержание
–    список рисунков и таблиц
–    приложения
–    глоссарий
–    перечни обозначений и сокращений
–    указатель
–    порядок    Не приводится
В содержании должны быть приведены заголовки всех частей, глав и разделов с указанием номеров страниц Не приводится Не предусмотрены
В глоссарии должен быть определен любой термин, неизвест¬ный аудитории пользователей документа, в терминах, знако¬мых данной аудитории
Следует указать все встречающиеся в тексте обозначения и сокращения. Если данные элементы не являются очевидными по смыслу, они должны быть пояснены соответствующим тек¬стом
В соответствии с Н.3
Располагаются в порядке их перечисления в настоящей табли¬це, основная часть документа располагается между содержа¬нием и глоссарием
Гарнитуры шрифтов и кегли текста основ¬ной части документа    Times Roman, 12 п
Отступы по горизонтали и пробелы по вер-тикали в тексте основной части    Текст основной части должен иметь общий отступ на 2 п и левосторонний отступ на 30 мм/7 цицеро. Между абзацами дол-жен быть вертикальный пробел в одну строку
Выравнивание текста основной части    Текст основной части должен быть выровнен по левой сторо¬не с неровностями по правому краю
Количество уровней и наименования за-головков    Четыре; заголовки части, главы, раздела и подраздела
Стиль текста заголовков    Все заголовки должны быть изложены в повествовательном стиле с заглавной буквы и без точки в конце
Гарнитуры шрифтов, кегли и отступы для каждого уровня заголовков    Все заголовки оформляют шрифтом Times Roman следую¬щими кеглями: заголовок части — 36 п, главы — 24 п, раздела — 18 п, подраздела — 14 п. Заголовки должны быть вы¬ровнены по левому краю.
Вверху каждого заголовка должен быть пробел, равный двум кеглям данного заголовка, за исключением расположения за-головка вверху страницы. Внизу каждого заголовка должен быть пробел, равный кеглю данного заголовка
Графические элементы, используемые в заголовках    Не используются
Колонтитулы:
–    верхние
–    нижние    Содержат название главы и раздела. Название главы распо-лагают со стороны переплета
Содержат номер страницы со стороны, противоположной переплету, с указанием на противоположной стороне номера версии, даты ее выпуска и наименования документа
Гарнитуры шрифтов, кегли и расположе¬ние колонтитулов:
–    верхний
–    нижний    Times Roman, кегль 12 п, колонтитулы расположены вверху каждой страницы за исключением титульного листа Times Roman, кегль 12 п, номер страницы кегль 12 п, колон¬титулы расположены внизу каждой страницы за исключением титульного листа

Продолжение таблицы Н. 1
Элемент    Значение
Графические элементы колонтитулов:
–    верхний
–    нижний    Должен быть подчеркнут линией толщиной в 1 п с вертикаль¬ным пробелом в 1 п
Должен быть надчеркнут линией толщиной в 1 п с вертикаль¬ным интервалом в 1 п
Надпись    Начинается с номера рисунка с двоеточием и текстом, на¬пример «Рисунок 1: . . .»
Гарнитуры шрифта, кегль и расположение надписей    Times Roman italics, кегль 10 п. Надписи должны быть распо-ложены под рисунком
Таблицы    Ширина таблиц должна соответствовать формату текста ос-новной части документа, а для их обрамления используют линии толщиной в 1 п
Гарнитуры шрифтов и минимальные кег¬ли для таблиц    Times Roman, минимальный кегль в 8 п
Отчеты (сообщения)    Должны содержать правдоподобные (но не фактические) дан¬ные
Гарнитуры шрифтов и минимальные кег¬ли для отчетов    Courier, минимальный кегль в 8 п
Компоновка отчетов    Должны быть представлены в горизонтальной (альбомной) компоновке без использования страниц-раскладок
Распечатки экранов:
–    содержание
–    оформление
–    частичные (т. е. представляющие часть экрана)    В каждом поле распечаток экранов должны быть представлены правдоподобные (но не фактические) данные Не должно быть горизонтальных или вертикальных искажений. Их ширина должна соответствовать формату набора Должны быть в масштабе полноэкранных распечаток
Минимальная толщина линий, гарнитуры шрифтов и кегли для рисунков    0,5 п, шрифт Times Roman, минимальный кегль в 8 п
Рисунки    Рисунки и текст внутри них должны располагаться соответ-ственно тексту основной части документа
Стиль текста уведомлений и предостереже¬ний    Стиль повествовательный, начинается со слова «Внимание:» или «Осторожно:»
Гарнитуры шрифтов, кегли и отступы для уведомлений и предостережений    Times Roman, кегль 24 п, расположение — по центру страни¬цы, пробелы сверху и снизу, интервалы сверху и снизу — рав¬ные двум строкам
Справочный текст    Должны быть обеспечены возможности создания контекстных и расширенных справок, справок о клавишах, справок о справ¬ках и терминологических справок
Диалоговая документация    Должна содержать руководства для пользователя, командные справки, рекомендации по сообщениям и административную информацию

Окончание таблицы Н.1
Элемент    Значение
Сопутствующие материалы    Информация по одной тематике по возможности должна рас-полагаться на одном экране
Подсветка и использование цвета    Цветовое оформление в диалоговой документации и справоч¬ных текстах не используют. Подсветку (более яркую цветовую тональность) используют только для заголовков
Диалоговая документация и справочный текст    Вверху отображаемого текста оставляют пустую строку (то есть между заголовком или верхом экрана и первой строкой текста). Формат текста — одноколонный
Заголовки диалоговой документации и справочного текста    Заголовки подсвечивают, используя более яркую цветовую тональность. Применяют только два уровня заголовков. Заго¬ловки излагают в повествовательном стиле (см. 8.2.3.7.2). Сверху и снизу каждого заголовка оставляют пробел, равный одной строке
Текст основной части электронной доку-ментации    Должен быть выровнен по левой стороне, допускаются не-ровности по правому краю. Слева от каждой строки текста ос-тавляют пробел, равный 20 символам
Правила навигации    Уровни расположения взаимосвязанной информации должны быть организованы и контролироваться так, чтобы пользова¬тели могли легко возвращаться в исходную точку (пункт), со¬держание или указатель без блуждания в тексте документа
Клавиатура    Должны быть использованы следующие клавиши: F1 — для вызова справочной системы: Alt-F1 или Еsc — для выхода из справочной системы. Никакие данные, введенные пользовате¬лем ранее, не должны быть потеряны при возврате из спра¬вочной системы к основному экрану
* Цицеро — шрифт, кегль которого равен 12 п (~ 4,51 мм).

Н.3 Спецификация указателя
Н.3.1 О б щ и е п о л о ж е н и я
Каждый документ, содержащий более 32 страниц, должен иметь указатель.
П р и м е ч а н и е — Указатель должен охватывать все компоненты документа, включая вводные материалы, приложения, дополнения и рисунки.
Н.3.2 К а ч е с т в о
Указатель должен быть достаточно подробным, чтобы удовлетворить потребностям соответствующих аудиторий.
П р и м е ч а н и е — Указатель должен занимать от 5 % (для учебных руководств) до 10 % (для справочных руководств) общего объема данного документа. Следует рассмотреть возможность использования профессиональных классификаторов.
Н.3.3 С о с т а в (с о д е р ж а н и е) и о р г а н и з а ц и я у к а з а т е л я
Весь комплект документации должен иметь единый указатель, если иное не оговорено в плане докумен-тирования.
П р и м е ч а н и я
1    В качестве заголовков (элементов) указателя (слов или фраз, вносимых в указатель) следует использо¬вать объекты, выбранные из конкретного документа (например, «программное средство»).
2    Для представления одинакового понятия должен использоваться один и тот же термин.
3    В указателе могут быть использованы подзаголовки, описывающие некоторые аспекты основного заго-ловка.
4    Заголовки указателя должны представлять основные понятия из конкретного документа. Для них сле¬дует использовать имена существительные, при необходимости дополняя их прилагательными, другими суще-ствительными или глаголами. В качестве заголовков могут быть взяты машинные команды, использованные в документации и представленные в виде глагола.
5    Термины, состоящие из нескольких слов, следует применять как заголовки без разбивки их на подзаго¬ловки.
6    Следует избегать использования предлогов, если их отсутствие не приводит к неоднозначному понима¬нию термина.
7    Понятия, отражающие различные аспекты одного объекта, должны быть перечислены как подзаго¬ловки основного заголовка указателя.
8    Сокращения и обозначения должны быть расположены а алфавитном порядке (например, обозначе¬ние «BASIC» для «Beginner’s All-purpose Symbolic Instruction Code» между «Base» и «Bettery»).
9    Заголовки указателя должны располагаться в алфавитном порядке, пробел должен трактоваться как символ, предшествующий последующему (например, термин «Alt key» размещается перед «Alternative»).
Н.3.4 С п р а в о ч н ы е c с ы л к и
Для каждого элемента (заголовка, подзаголовка) указателя должны быть даны локальные ссылки при отсутствии перекрестных ссылок.
В справочных ссылках должен быть указан либо номер страницы документа (например, 1, 2), либо номера раздела, подраздела и т. д. (например, «2.22», «3.34»). При указании рисунков справочные ссылки могут быть даны на их номера.
П р и м е ч а н и я
1    Обычно пользователям удобнее пользоваться ссылками на страницы, чем на разделы документа.
2    Для элементов указателя не следует использовать большие перечни локальных ссылок. Максимально удобными для работы являются пять ссылок (например, 1, 33, 43, 99, 102). Во избежание длинных перечней локальных ссылок следует использовать подзаголовки.
3    Ссылки, подлежащие обсуждению, могут быть выделены шрифтом (гарнитурой, кеглем).
4    Если перечень подзаголовков охватывает несколько колонок (столбцов), вверху каждой колонки должно быть указано наименование основного заголовка со словом «продолжение».
5    Если используют особую последовательность нумерации страниц, она должна быть указана в указателе. Например, если нумерация начинается с номера каждой главы, данный номер должен быть указан в локаль¬ной ссылке, то есть «2—22, 3—34».
6    Если элемент указателя используют в нескольких частях документа, нумеруемых последовательно, в локальной ссылке должны быть указаны только первые и последние номера, разделенные тире (например, 3—11). Когда тире используют в нумерации страниц, для разделения страниц тире не используется (например, 3—6 до 3—8).
Н.3.5 П е р е к р е с т н ы е с с ы л к и
В перекрестных ссылках на сокращения, синонимы или альтернативные виды термина, выбранные из элементов указателя, следует использовать сокращение «См.» (например, проект — см. оформление).
П р и м е ч а н и е — Дополнительно перекрестная ссылка с сокращением «См.» может быть дана на другие элементы документа. За перекрестной ссылкой не следует использовать локальную ссылку.
Перекрестная ссылка со словами «См. также» может быть дана из более обширного термина на менее исчерпывающие термины, если не используется прямая локальная ссылка.
П р и м е ч а н и е — Перекрестные ссылки со словами «См. также» следует использовать для взаимоувяз¬ки терминов в интересах пользователя. Перекрестная ссылка со словами «См. также» под основным элементом указателя должна объединять ряд связанных элементов указателя, имеющих справочные ссылки. Например Рисунки 4
см. также графические элементы; распечатки экранов
индексирование 12
список 15
нумерация 2
Слова «См.» и «См. также» обычно выделяют курсивом.
Библиография
В нижеперечисленных публикациях содержится более подробная информация по некоторым темам, связанным с настоящим стандартом.
Соответствующие международные и национальные стандарты
[1]    ИСО/МЭК 6592—2000 Информационная технология. Руководство по документированию прикладных ав-томатизированных систем
[2]    BS 7649—93 Руководство по проектированию и выпуску документации пользователей прикладных программных средств
Общие положения
[3]    Barnum C. M. and Capliner S. Techniques for Technical Communicators, MacMillan, 1993
[4]    Brockmann R. J. Writing Better Computer User Documentation, Wiley, 1990
[5]    Brusaw C. T., Alred G. J. and Oliu W. E. Handbook of Technical Writing, St. Martin’s Press, 1993
[6]    Burnett R. E. Technical Communications, Wadsworth Publishing, 1994
[7]    Hackos J. T. Managing Your Documentation Projects, Wiley, 1994
[8]    Holtz H. The Complete Guide to Writing Readable User Manuals. Dow Jones-Irwin, 1988
[9]    Horton W. K. Illustrating Computer Documentation. Wiley, 1991
[10]    Simpson H. and Casey S. M. Developing Effective User Documentation: A Human Factors Approach. МсGraw- Hill, 1988
[11]    Weiss E. H. How to Write Usable User Documentation, Oryx Press < 1991
[12]    Zinsser W. On Writing Well, Harper and Row < 1994
Диалоговая документация и гипертекст
[13]    Bogan S., Farkas D. and Wellinske J. Developing On-Line Help for Windows, International Thomson Press, 1995
[14]    Brown C. M. Human-Computer Interface Design. Norwood, 1988
[15]    Helander (Ed). Handbook of Human-Computer Interaction. North Holland
[16]    Horton W. K. Designing and Writing On-line Documentation. Help Text to Hypertext. Wiley, 1990
[17]    Horton W. K. Designing and Writing On-line Documentation: Hypermedia for Self—Supporting Products, Wiley, 1994
[18]    Laurel and Mountford, The Art of Human-Computer Interface Design. Addison—Wesley, 1990
[19]    Van Der Veer and Mulder, Human-Computer Interaction. Springer—Verlag, 1988
Тестирование на практичность
[20]    Dumas J. S. and Redish J. C. А Practical Guide to Usability Testing, Ablex Publishing, 1993
[21]    Nielson J. Usability Engineering, AP Professional, 1993
Тематический указатель
авторские права
в плане документирования    8.1.3.1g
в образце плана    С.7
обязанности заказчика    8.1
при оценке плана документирования    приложение G
формулировка    8.2.3.5b
активный разделитель, определение    4.54
алфавитный порядок в указателе    Н.3.3
альбомная (горизонтальная) ориентация    8.2.3.1.2, 8.2.3.11.4
анализ требований    8.1.3
Аудитория
доступ    8.1.2d
изучение    4.4, В.1
образец плана    С.4
описание    8.1.3.1, 8.1.3.2, приложение G
определение    4.3
библиография    библиография
описание для перевода    приложение Е
бумага     8.2.3.1.8
размер (формат)    8.2.3.1.1
бумажная документация    8.2.3
определение    4.34
вводный материал
определение    4.21
спецификация     8.2.3.5
верхний колонтитул    4.22
взаимодействие между заказчиком и документатором    8.1.4.1
вопросы законности    8.1.4.1
Время
необходимое    8.1.3.1
оценка    приложение F
вспомогательный материал
определение    4.6
спецификация     8.2.3.5
выравнивание текста
в бумажной документации    8.2.3.6.4
в диалоговой документации    8.2.4.3.6
грамматика     . 8.2.2.3
Гранки
определение    4.40
количество копий    В.1Ь
проверка     8.1.4.5
графические элементы
в диалоговой документации    8.2.4.3.7
верхние и нижние колонтитулы    8.2.3.8
заголовки    8.2.3.7
необходимое время для разработки    F.2
описание для перевода    Е.4
уведомления и предостережения    8.2.3.14
дата пересмотра    4.8
даты (при переводе)    Е.6И
двусторонняя печать    8.2.3.1.3
верхние и нижние колонтитулы    8.2.3.8
диалоговая документация    8.2.4.2
в плане документирования    8.1.3.1
описание для перевода    Е.5
определение    4.31
длина строки    8.2.3.6.3
Договор
использование настоящего стандарта    приложение В
образец раздела договора, соответствующий стандарту    В.3
собственник авторских прав    8.1.3.1g
документ с замененными страницами
таблица действующих страниц    8.1.7.2с
документатор    4.14
документация    4.11
доступ к аналитикам    8.1.2с
доступ к оформлению экранов    8.1.2а
доступ к программистам    8.1.2с
доступ к техническим требованиям (условиям)    8.1.2
доступ к форматам записей    8.1.2а
жаргонные выражения    E6f
завершение разработки плана документирования    8.1.3.2
Заголовки
в бумажной документации    8.2.3.7
в диалоговой документации    8.2.4.3.5
в указателе    Н.3.3, примечание 1
определение    4.23
Заказчик
определение    4.2
требования    8.1.3.1
защита (документации)    8.1.4.1
защита, предусмотренная договором    8.1.2, В.1
измененный документ (изменение документа)    4.28
интервалы по вертикали    8.2.3.6.3
интерфейс пользователя    4.51
информация для администратора в диалоговых справочных системах    8.2.4
информация о торговой марке    8.2.3.5b
иронические выражения    Е.6е
использование верхних колонтитулов    8.2.3.8
использование клавиатуры в диалоговой документации и справках    8.2.4.3.8
использование концевых примечаний    8.2.3.3
использование нижних колонтитулов    8.2.3.8
использование сносок    8.2.3.3
использование страниц-раскладок    8.2.3.11.4
использование языка    8.2.2.1
календарный план (график)    8.1.3.1s
в образце плана    С.14
книжная (вертикальная) ориентация    8.2.3.1.2
колонки    8.2.3.6.2
командные справки в диалоговой справочной системе    8.2.4.2
компактность бумажной документации    8.2.3.1.1е
контекстная справка (диалоговая)    8.2.4.1а
контроль
в образце плана    С.9
плана документирования    8.1.3.3
планирования    8.1.3.1
контроль изменений    8.1.7
договора    приложение В
в плане документирования    8.1.3.3
не связанных с областью действия договора    8.1.4.1, примечание 2
оценка временных затрат    F.3.6
плана    8.1.3.1q
контрольные точки (этапы)    8.1.3.1s
конфиденциальность, предусмотренная договором    8.1.2
концевые примечания    4.17
копирование плана документирования    8.1.3.3
краткие справочные карты    8.1.3.1
края и нумерация страниц    8.2.3.1, 8.2.3.2 культурные особенности (при переводе)    Е.6
математические символы    Е.3.1
метод нисходящего проектирования при оценке    F.3
Навигация
в диалоговой документации и справочных текстах    8.2.4.3.7
определение    4.30
надписи    8.2.3.9
нижний колонтитул    4.19
номенклатура поставки
в образце плана    С.6
определение    4.9
нотация метрических величин для перевода    Е^
область применения
в образце плана    С.2
документации    8.1.3.1а
настоящего стандарта    1
обозначения
в указателе    Н.3
описание для перевода    Е.2
перечень    8.2.3.5
образец
договора    приложение В
оформления    приложение Н
плана документирования    приложение С
обязанности проверяющей стороны (эксперта)    8.1.4.1
ограничения документации    8.1.4.1
односторонняя печать    8.2.3.1.3
определения    4
оригинал-макеты    8.2
определение    4.29
ориентация
рисунков    8.2.3.13.2
страниц    8.2.3.1.2
орфография
в редакции (проекте) документации    8.1.4.3
правила    8.2.2.2
отступы по горизонтали    8.2.3.6.3
отступы, интервалы, пробелы
в диалоговой документации    8.2.4.3.4
в тексте основной части    8.2.3.6
для перевода    Е.4
отчеты    8.2.3.11
оформление
бумажной документации    8.2.3.1
выдаваемых материалов    8.1.2
диалоговой документации    8.2.4.3.4
образец    приложение Н
образец плана    приложение С
по настоящему ставдарту    В.2
принятых решений    8.1.3.1
распечаток экранов    8.2.3.12.2
редакций (проектов) документации    8.1.4.3, 8.1.4.4
таблиц    8.2.3.10.1
текста основной части документа    8.2.3.6
оценка плана документирования    приложение G
оценка (проекта)    приложение F
пагинация    8.2.3.4
пассивный разделитель    4.55
перевод
в образце плана    С.8
в плане документирования    8.1.3.1h
правила    приложение Е
перекрестные ссылки (в указателе)    Н.3.5
переплет
график переплетения    8.1.3.1s5
метод     8.2.3.1.11
период планирования    F.3.3
персонал разработчиков документации    4.12
печать
календарное планирование    8.1.3.1s
метод и качество    8.2.3.1.10
разрешающая способность    8.2.3.1.4
пиктограммы
в верхних и нижних колонтитулах    8.2.3.8.3
в заголовках    8.2.3.7.4
план выбора группы проектантов    4.47
план документирования    8.1.3
контроль    8.1.3.3
образец    приложение С
определение    4.13
оценка    приложение G
проверка    8.1.4.2
специальные функциональные клавиши    8.2.4.3.8, примечание 2
уровень тестирования на практичность    8.1.5.1
подзаголовки (в указателе)    Н.3.3, примечание 3
подсветка в диалоговой документации    8.2.4.3.3
полнота (документации)    8.1.4.1
пользователи
определение    4.52
определение аудитории    8.1.3.2
участие в тестировании на практичность    8.1.5.4
поля
внешние    8.2.3.1.6
внутренние    8.2.3.1.5
понятийная справка (диалоговая справка)    8.2.4.1g
правила для строк    8.2.3.6.3
правила плотности документа    8.2.3.4
правильность    8.1.4.1
практическая лаборатория    4.49
практическое применение настоящего стандарта    приложение В
предлоги в указателе    Н.3.3, примечание 6
предостережения    8.2.3.14
представление исходных материалов    8.1.2, В.1
приложения
проект     8.1.4.3
местоположение    8.2.3.5е
применение клавиатуры для диалоговой документации    8.2.4.1с
применение ставдарта    1
примеры
описаний для перевода    приложение Е
принятая редакция    F.3.6
проверка    8.1.4
необходимое время    приложение G
ориентировочное время    F.3.6
после создания (документации)    8.1.3.1r
проверки документации после ее создания    8.1.3.1.2r
проверки плана документирования    8.1.4
проверка редакции (документации)
второй    8.1.4.4, F.3.5
калевдарный план    8.1.3.1s
необходимое время    F.3.6, приложение G
первой    8.1.4.3, F.3.4
число редакций    В.1Ь
программные средства
доступ     8.1.2
изменения    8.1.7
использование при тестировании на практичность    8.1.5.3
описание для перевода    Е.5
продукция     4.38
проектанты
в образце плана    С.11
выбор и структура    4.47, 8.1.3.11
производство
в образце плана    С.10
определение    4.39
при оценке плана документирования    приложение G
при подготовке плана документирования    8.1.3.1.k
простонародные выражения    E6f
прототип    4.41
процедуры и контроль передачи    8.1.3.1j
процедуры резервирования    8.1.3.1j
процедуры, указанные в плане    8.1.3.1j
пунктуация
в редакции (проекте) документации    8.1.4.3
при описании для перевода    Е.3.4
рабочее место для работы с документацией    8.2.3.1.1е
рабочее наименование    8.1.3.1а
разделитель    8.2.3.4
активный    4.54
пассивный    4.55
разделители    8.2.3.1.9
разметка шрифтов    8.1.4.1, примечание 7
разрешающая способность (печати)    8.2.3.1.4
разрешающая способность лазерной печати    8.2.3.1.4
разрешающая способность типографской лазерной печати    8.2.3.1.4
распечатки экрана    8.2.3.12
генерация (создание)    8.1.4.1, примечание 4
определение    4.43
размер (формат) бумаги     8.2.3.1.1
распространение
календарного планирования    8.1.3.1
плана документирования    8.1.3.3
расширенная справка (диалоговая)    8.2.4.1b
редактирование проекта документации    8.1.4.3, примечание 1
рекомендации по сообщению в диалоговой системе    8.2.4.2с
ресурсы (в образце плана)    С.12
решение вопросов    8.1.2с
рисунки    8.2.3.13
в указателе    Н.3.1
нумерация    8.2.3.2.2
описание для перевода    Е.4
список     …     …     …     …     …     .. 8.2.3.5d
руководства пользователя в диалоговой документации    8.2.4.2а
связанная информация в диалоговой документации    8.2.4.3.7, примечание 1
символы валют    Е.3.1
синтаксис (для перевода)    Е.3.3
система     4.44
системы поиска     . 8.1.3.1
словарь (орфографический)    8.2.2.2
словарь
в редакции документации    8.1.4.3
описание для перевода    Е.2
расположение в документации    8.2.3.5f
терминов, использованных в настоящем стандарте    4
сноска    4.20 содержание
в образце плана    С.5
в плане документирования    8.1.3.1е
в редакции (проекте) документации    8.1.4.3
определение    4.45
оформление    8.2.3.5
при оценке плана документирования    приложение G
сокращения
в указателе    Н.3
перечень    8.2.3.5
описание для перевода    Е.2
сопровождение документации    8.1.7
план    8.1.3.1q
составные выражения    E2g
специальные функциональные клавиши    8.2.4.3.8
справочный перечень    библиография
справка о сообщении (диалоговая справка)    8.2.4.1е
справочные ссылки    Н.3.4
определение    4.27
справочный текст    4.25
стандарты    8.2.1
доступ к     8.1.2
по управлению качеством    5
стиль описания    8.2.2
в образце плана    С.3
руководство     . . 8.1.2
стоимость документирования    8.1.3.1
страницы
номер    8.1.3.1
нумерация    8.2.3.2
оформление    8.2.3
оценка количества    приложение F
страница-развертка    8.2.3.11.4
определение    4.48
страница-раскладка    4.18
субподряд    8.1.6
в плане документирования    8.1.3.1, примечание 2
схемы нумерации    8.2.3.2
в указателе    Н.3.4
таблицы    8.2.3.10
нумерация    8.2.3.2.2
список     …     …     …     …     …     .. 8.2.3.5d
таблица действующих страниц    8.1.7.2с
определение    4.46
текст
диалоговой документации    8.2.4.3.4
заголовки    8.2.3.7
необходимое время для разработки    приложение F
оформление    8.2.3.6
уведомления и предостережения    8.2.3.14
цвета    8.2.3.1.7
текст основной части
бумажной документации    8.2.3.6
диалоговой документации    8.2.4.3.6
терминологическая справка (диалоговая справка)    8.2.4.1f
терминология
описание для перевода    Е.2
определения    4
тестирование на практичность    8.1.5
взаимосвязь с пользователями    8.1.2
в образце плана    С.13
калевдарный план    8.1.3.1s 3 определение    4.50
типовые пользователи    8.1.5.4
доступ к     8.1.2
типы справочных текстов (информации)    8.2.4.1
титульный лист    8.2.3.5а
уведомления    8.2.3.14
указатель    Н.3
в первой редакции (документации)    8.1.4.3
управление качеством    5
при планировании    8.1.3.1
связанное с взаимодействием субъектов    8.1.4.1
форматы бумаги А4 и А5    4.1, 8.2.3
формат бумаги В5    4.5, 8.2.3
формулировка гарантий    8.2.3.5b
формулировка компенсаций    8.2.3.5b
фотокопирование    8.2.3.1.1d
фотошаблоны
график изготовления    8.1.3.1s 4
определение    4.7
оценка    F.3.6
функциональные клавиши (диалоговая документация)    8.2.4.3.8
цвет
бумаги    8.2.3.1.8
в диалоговой документации    8.2.4.3.3
красок ..     ..     ..     ..     . 8.2.3.1.7
шрифт (гарнитура, кегль и расположение)
в верхних и нижних колонтитулах    8.2.3.8
в диалоговой документации    8.2.4.3.4
в заголовках    8.2.3.7
в надписях    8.2.3.9
в основной части документа    8.2.3.6
в отчетах    8.2.3.11
в таблицах    8.2.3.10
в уведомлениях и предостережениях    8.2.3.14
компоновка    8.2.3.6 — 8.2.3.8
электронная копия    4.15
элемент документации    4.26
юмористические выражения    E6d
УДК 681.3.06:006.354    ОКС 35.080    П85    ОКСТУ 5001
Ключевые слова: обработка данных, вычислительные машины, программные средства вычислитель¬ных машин, документирование, документация пользователя
Редактор Б. П. Огурцов Технический редактор Б. Н. Прусакова
Корректор Е. Д. Дульнева Компьютерная верстка Б. Н. Романовой
Изд. лиц. № 02354 от 14.07.2000. Подписано в печать 16.09.2002. Усл. печ. л. 5,58. Уч.-изд. л. 5,60. Тираж 440 экз.
С 7303. Зак. 754
ИПК Издательство стандартов, 107076 Москва, Колодезный пер., 14. http://www.standards.ru e-mail: info@standards.ru Набрано в Калужской типографии стандартов на ПЭВМ. Филиал ИПК Издательство стандартов — тип. «Московский печатник», 103062 Москва, Лялин пер., 6.
Плр № 080102

Комментарии закрыты.

ocnova.ru

Р ИСО/МЭК 15910-2002 Процесс создания документации пользователя программного средства

ГОСТ Р ИСО/МЭК 15910-2002 ГОСУДАРСТВЕННЫЙ СТАНДАРТ РОССИЙСКОЙ ФЕДЕРАЦИИ

Информационная технология

ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ

ПРОГРАММНОГО СРЕДСТВА

Содержание

Введение

1 Область применения

2 Соответствие

3 Нормативные ссылки

4 Определения

5 Управление качеством

ПРИЛОЖЕНИЕ В (справочное)

ПРИЛОЖЕНИЕ С (справочное)

ПРИЛОЖЕНИЕ D (справочное)

ПРИЛОЖЕНИЕ Н (справочное)

Н.3 Спецификация указателя

Библиография

Обо мне

наши партнеры

Неизвестная лента

Неизвестная лента

Опрос

Свежие записи

Архивы

Мета

ocnova.ru

Р ИСО/МЭК 15910-2002 Процесс создания документации пользователя программного средства

ГОСТ Р ИСО/МЭК 15910-2002 ГОСУДАРСТВЕННЫЙ СТАНДАРТ РОССИЙСКОЙ ФЕДЕРАЦИИ

Информационная технология

ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ

ПРОГРАММНОГО СРЕДСТВА

Содержание

Введение

1 Область применения

2 Соответствие

3 Нормативные ссылки

4 Определения

5 Управление качеством

ПРИЛОЖЕНИЕ В (справочное)

ПРИЛОЖЕНИЕ С (справочное)

ПРИЛОЖЕНИЕ D (справочное)

ПРИЛОЖЕНИЕ Н (справочное)

Н.3 Спецификация указателя

Библиография

Обо мне

наши партнеры

Облако меток

Неизвестная лента

Неизвестная лента

Опрос

Свежие записи

Архивы

Мета