ГОССТАНДАРТ РОССИИ - Информационная технология ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА

Существующие стандарты можно отнести к двум основным типам:

a) стандарты на продукцию, определяющие ее характеристики и требования к ней;

b) стандарты на процессы, определяющие конкретные методы создания продукции.

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

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

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

Более подробная информация по данному вопросу приведена в библиографии.

Примечания

1 Основной стандарт дополнен справочными приложениями, библиографией и тематическим указателем.

2 Исходный стандарт ИСО/МЭК 15910 разработан на основе австралийского стандарта AS 4258:1994.

3 Перечень дополнительных публикаций, связанных с тематикой настоящего стандарта, приведен в библиографии (см. [1] — [21]).

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

Стандарт соответствует требованиям 6.1 ГОСТ Р ИСО/МЭК 12207.

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

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

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

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

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

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

В настоящем стандарте использованы ссылки на следующие стандарты: ГОСТ 2.301-68 Единая система конструкторской документации. Форматы ГОСТ Р ИСО 9127-94 Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов

ГОСТ Р ИСО/МЭК 12119-2000 Информационная технология. Пакеты программ. Требования к качеству и тестирование

ГОСТ Р ИСО/МЭК 12207-99 Информационная технология. Процессы жизненного цикла программных средств

ИСО 216-75[1] Бумага писчая и классы печатных материалов. Размеры обрезки. Серии А и В.

В настоящем стандарте использованы следующие термины с соответствующими определениями.

4.1 А4, А5: Размеры сторон листа 210×297 мм и 148?×210 мм соответственно (см. ИСО 216, ГОСТ 2.301).

4.2 заказчик (acquirer): Организация, которая приобретает или получает систему, программный продукт или программную услугу от поставщика (3.1 ГОСТ Р ИСО/МЭК 12207).

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

4.3 аудитория (audience): Категория пользователей, предъявляющих к документации одинаковые или аналогичные требования и характеристики (например, в части использования документации, ее назначения, уровня обучения, возможностей и опыта персонала), определяющие содержание, структуру и назначение данной документации.

Примечание — Одна и та же программная документация может использоваться различными аудиториями (например, руководством, операторами по вводу исходных данных или сопроводителями).

4.4 изучение аудитории (audience research): Планируемый процесс опроса потенциальных пользователей и анализа его индивидуальных и интегральных результатов.

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

4.5 В5: Размеры сторон листа 176×250 мм (см. ИСО 216).

4.6 вспомогательный материал (back matter): Материал, содержащийся в конце книги или руководства, например, тематический указатель.

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

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): Примечания, собранные в конце главы или документа.