(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 laboratory): Комплекс аналитических и исследовательских помещений, оснащенных видео- и аудиооборудованием для регистрации ответов на запросы пользователей.
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.
6 Адаптация
Настоящий стандарт определяет одну из реализаций процесса документирования, описанного в ГОСТ Р ИСО/МЭК 12207, и может быть адаптирован к условиям конкретных проектов (см. приложение В).
7 Цели
Настоящий стандарт по существу является стандартом на процесс. Стандарт не определяет компоновку конкретного документа, его содержание и другие аспекты комплектности документации, однако он устанавливает метод планирования и проведения процесса документирования.
8 Требования
8.1 Процесс документирования
8.1.1 Общие положения
Процесс документирования должен быть выполнен в два этапа в последовательности, представленной на рисунке 1 в затененных прямоугольниках. Поэтапные работы не выполняются одновременно. На отдельных этапах работы могут проводиться параллельно. Возможные итерации работ показаны пунктирными линиями.
Когда минимальный состав документации определяется заказчиком (например, с использованием ГОСТ Р ИСО 9127 или ИСО/МЭК 6592 [1]), это должно быть учтено документатором при разработке плана документирования.
8.1.2 Представление исходных материалов
Заказчик должен обеспечивать документатору доступ:
a) ко всем соответствующим спецификациям, форматам записей, компоновкам экранов и отчетов, выходным результатам работы средств автоматизации программирования (CASE 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);
o) требования к проектным ресурсам, включая информационные и прочие ресурсы, представляемые заказчиком, и срокам их представления;
р) метод передачи документатору информации об изменениях программного средства в процессе его разработки;
q) планы контроля изменений и сопровождения документации (факультативно);
г) планы проверки документации после ее создания;
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) дополнительно был предусмотрен метод, позволяющий пользователю контролировать соответствие конкретной копии данного документа используемой версии программного средства.
В договоре должно быть оговорено, что изменения каждого типа вносятся в документацию документатором.