Страница 6: ДСТУ ISO/IEC 15910:2012. Інформаційні технології. Документування програм. Документація користувача (61132)

Має бути визначено правила щодо навігації.

Примітка 1. Треба контролювати рівні зв'язаної інформації таким чином, щоб користувач міг легко вернути в зада­ну точку, або до таблиці змісту чи то до покажчика, не відчуваючи себе загубленим всередині документа

Примітка 2. Структурні «правила» щодо документа треба розробляти та застосовувати послідовно. Наприклад, кількість зв’язків у кожному інформаційному ланцюгу має бути обмежено величиною X, а значення X таке, що користувачі повинні мати часту та постійну нагоду вертати до таблиці змісту й переорієнтувати себе всередині документа. Рівні заголовків також можуть бути прив'язані до рівнів складності (тобто «Заголовки рівня 1 дають тільки оглядову інформацію»)

Примітка 3. Зорієнтовану на завдання та концептуальну інформацію треба розділити на дискретні розділи, вста­новивши зв’язки між їхніми точками входу Це повинно оберігати користувачів, що намагаються опанувати певне зав­дання від мимовільного заглиблення у концептуальний матеріал, що може заплутати або відволікти їх.

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

Примітка 5. Розділ, що направляє користувачів, треба поміщати на початку документа, забезпечуючи базову інфор­мацію про використовування діалогової інформації. Цей розділ треба використовувати для пояснення структури документа та будь-яких структурних «правил», застосовних до нього.

Національна примітка

У національних стандартах замість терміна «дугова хвилина» поза системи одиниці виміру площинного кута засто­совують термін «хвилина», який позначають «'», і всі його співвідношення системною одиницею Sl:1’ = 1/60° 1 п/10800 PAS

Має бути визначено правила щодо застосування спеціальних клавіш для діалогової документації.

Примітка 1. Користувач повинен мати змогу викликати довідку за допомогою тієї самої клавіші або клавішної комбі­нації у будь-якій точці програми. Користувач також повинен мати змогу викликати діалогову документацію за допомогою однієї клавіші клавішної комбінації

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

Примітка 3. Застосовування клавіш спеціального функційного призначення має бути, по можливості, узгоджено з застосовуванням функційних клавіш у самому програмному забезпеченніДОДАТОКA
(довідковий)

ПЕРЕХРЕСНІ ПОСИЛАННЯ НА ISO/IEC 12207

Цей стандарт відповідає стандарту ISO/IEC 12207:1995 «Інформаційні технології. Процеси життєвого циклу програмного забезпечення» як реалізація частини щодо документації користу­вача, а саме: 6.1 Документування, як показано у таблиці А.1.

Таблиця А.1 — Перехресні посилання на ISO/IEC 12207

ДОДАТОК В
(довідковий)

ЗВЕРНЕННЯ ДО ЦЬОГО СТАНДАРТУ У КОНТРАКТІ

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

Крім того, з ціллю пояснення контракту часто звертаються до плану документування.

У контракті має бути охоплено такі питання:

1. Яке походження інформації, отриманої в результаті дослідження кола користувачів? (Визначати це необов’язково, але рекомендовано).

2. Чи потрібно забезпечити більше двох копій попередніх версій та однієї копії коректури? (Це необов’язково: цей стандарт допускає дві попередні версії та одну коректуру).

3. Хто буде надавати вихідні матеріали? (Зазвичай це очевидно, але у проектах із склад­ними взаємозалежностями між сторонами краще виписати це явно).

4. Який рівень конфіденційності або захисту треба застосовувати щодо матеріалів, які надаються замовником постачальнику документації?

5. Чи чинний стандарт щодо макетування паперової документації, який треба використо­вувати? (Якщо це не явно визначено, то є необов’язковим. Специфікація стилю, визначена у цьому стандарті, може бути використана за промовчанням; кількість копій тощо, може бути визначено пізніше планом документування).

Приклад пункту, де є посилання на стандарт, може виглядати так:

Приклад

Пункт 123 документації

Документація користувача має відповідати вимогам стандарту ISO/IEC 15910. Документа­ція не повинна містити діалогові матеріали або підказки. Всі матеріали з дослідження кола користувачів та інші вихідні матеріали повинні бути надані замовником.

Під час постачання першого модуля треба провести один тест на придатність, який має охопити випробовування всієї функційності модуля із використовуванням п’яти різних типів користувачів.В.З Застосовування цього стандарту

За потреби, застосовування цього стандарту є в інтересах як замовника, так і постачаль­ника документації.

Застосовування, як правило, набуває форми вилучення або долучення пунктів за допомо­гою письмової угоди (зазвичай контракту, але можливо, також плану документування).

Застосовування цього стандарту має бути ретельним і тільки за умови досконалого знан­ня структури стандарту.

ДОДАТОК С

(довідковий)

ПРИКЛАД ПЛАНУ ДОКУМЕНТУВАННЯ: ДОКУМЕНТАЦІЯ КОРИСТУВАЧА
ДЛЯ СИСТЕМИ КЕРУВАННЯ ПЛІВКАМИ ABC

С.1 Вступ

Цей документ описує стратегію розроблення документації для системи керування стрічка­ми ABC, яку пропонує Документація XYZ (XYZ). Вона описує рамки проекту, елементи постачання та необхідні ресурси. Стратегія передбачає друковану документацію та діалогову документацію у формі підказок.

За потреби внесення змін до запропонованої стратегії, видають переглянутий план.

С.2 Рамки та обмеження

Документація не має інструкцій щодо використовування операційної системи, під керуван­ням якої працює ABC. Однак там, де це прийнятно, читача будуть відсилати до відповідних настанов для отримання подальшої інформації.

Документація щодо встановлювання, впроваджування та керування ABC вже наявна і не є предметом розгляду цього стандарту.

С.З Макет та стиль написання

Буде застосовано макет та стиль написання, визначені стандартом ISO/IEC 15910. Приклад сторінки долучають до цього плану документування.

Настанови щодо стилю діалогової документації наведено нижче у таблиці С.1.

Таблиця С.1 — Настанова щодо стилю

С.4 Коло користувачів

Коло користувачів складатимуть оператори комп’ютерів із низьким рівнем технічних знань. Мінімальний рівень, освіти користувачів — 12-річна школа.

Ніхто з кола користувачів не має значних вад щодо читання; допустимо, що всі мають до­статні навички читання.

Коло користувачів, ймовірно, повинно мати досвід від одного до двох років у частині опе­рацій комп’ютерного центру, до яких відносять такі оперативні процедури, як: пуск та зупинка, системи резервного копіювання та відновлення, а також завантаження та вивантаження стрічок. Обов’язки також охоплюють спостерігання та реагування на консольні повідомлення, пов’язані з функціонуванням системи.

Щодо знань користувача роблять такі припущення:

1. Користувач розуміє загальні процедури оброблення стрічок.

2. Користувач розуміє відповідні команди операційної системи.

3. Користувач не розуміє процедур оброблення стрічок із застосуванням ABC.

С.5 Попередня таблиця змісту

Попередня таблиця змісту охоплює таке:

1. Вступ: поняття ABC та її взаємозв’язок із системою (5 сторінок).

2. Огляд: огляд функції керування стрічками ABC (3 сторінки).

3. Долучення стрічки (5 сторінок).

4. Видалення стрічки (5 сторінок).

5. Проблеми: настанова щодо вирішення проблем, охоплюючи системні повідомлення (4 сторінки).

6. Глосарій термінів та визначення понять (1 сторінка).

д) Покажчик (1 сторінка).

Всього: 24 сторінки.

С.6 Елементи постачання

Наведені нижче елементи підлягають постачанню по закінченні розроблення проекту:

1. 500 копій настанови, зброшурованих за допомогою пружинного механізму;

2. Копія всієї документації на дискеті, формат DEF 3.0 (настроєний на GHI-принтер), 1,44 Мбайт, дискети 3,5 дюйми.

3. Копія підказок на дискеті.

С.7 Авторські права

Авторські права на всі матеріали залишаються у власності XYZ.

С.8 Переклад

Жодних умов щодо перекладу немає.

С.9 Процес розроблення та контролювання

Настанови користувачу для ABC будуть створюватися із застосовуванням процедур розроб­лення та контролювання, визначеним у настанові щодо керівництва якістю XYZ.

С.10 Розроблення

Для розроблення настанов користувача ABC буде застосовуватись видавнича система DEF (версія 3.0). Діаграми буде створено із застосуванням графічного пакета JKL.

Копії екранів ABC буде знято електронним способом та долучено до кінцевого документа. Таблицю змісту та покажчик буде настроєно та згенеровано із застосовуванням DEF.

Оригінал-макет основного примірника буде віддруковано на лазерному принтері з резолю­цією 300 dpi-точок на дюйм; однак за додаткову плату може бути продуковано високоякісний основний примірник із резолюцією 1275 dpi.

Кожна настанова матиме формат А4 з відривними аркушами, віддрукована із застосовуван­ням двостороннього друку та зброшурована за допомогою пружинного механізму.

Пружинний механізм матиме формат А4, з витяжними кільцями з корінцем 25 мм. Обкла­динка буде являти собою віддрукований екран з корпоративним дизайном ABC.

Паперова маса для настанов вибирається із щільністю 103 г/см², офсетна, матова.

Підказки буде розроблено із застосовуванням засобів розробника DEF.С.11 Проектна група

Проектна група та її обов'язки показано у таблиці С.2.

Таблиця С.2 — Проектна група

С.12 Ресурси

Інформація, потрібна для розроблення настанов, буде одержана з проектної документації ABC, інтерв’ю з розробниками програмного забезпечення та використовування ABC на практиці.

Група розроблення документації потребує таких ресурсів:

1. Копії документації з функційного проекту ABC.

2. Доступ до системи ABC.

3. Доступ до розробників програмного забезпечення ABC.