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

С.13 Тест на придатність

Після впровадження коментарів до другої попередньої версії буде проведено серію тестів на придатність «Настанови користувача та підказок для системи АВС» щодо їхнього використо­вування.

Ціллю тестування буде оцінювання того, якою мірою мова, зміст та макет «Настанови для користувача та підказки для системи АВС» дозволяють користувачам здійснювати доступ до можливостей програмного забезпечення.

Тести будуть проводити у комп’ютерній кімнаті й будуть використовувати тестову бета- версію АВС; під час тестування будуть присутні один представник групи розроблення програм­ного забезпечення та один представник групи розроблення документації.

З маси читачів документації буде вибрано чотири випадкових типових користувача з-поміж операторів нічної зміни, як встановлено вище (С.4). Кожному з них буде надано копію виправ­леної другої попередньої версії «Настанови користувача та підказок для системи АВС» і буде за­пропоновано виконати серію кроків (перерахованих у певному місці деталізованого плану з тестування).

Обидва представники будуть реєструвати час, що витрачено на кожний крок, коментарі користувачів та фізичний процес, через який проходять користувачі під час виконання кроків.

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

Ці нотатки буде винесено на обговорення на нараді з перегляду документації поряд із відпо­відними змінами до попередньої версії. Нарада також визначить потребу подальшого тестування.

С.14 Календарний план

Календарний план наведено у таблиці С.З.Таблиця С.З — Календарний план

ДОДАТОК D

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

ВЗАЄМОЗАЛЕЖНІСТЬ МІЖ КОЛОМ КОРИСТУВАЧІВ, ЗАВДАННЯМИ,
ПАПЕРОВОЮ ТА ДІАЛОГОВОЮ ІНФОРМАЦІЄЮ

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

Іноді найкращим способом представлення різних груп є ієрархія кіл користувачів, як пока­зано на рисунку D.1.

Рисунок D.1 — Ієрархія кіл користувачівЧасто виникає потреба уточнення визначення кола користувачів відповідно до того досвіду використовування системи, що його мають користувачі, які належать до заданого кола користувачів. Наприклад, кола користувачів можна визначити як «Користувачі-новачки» та «Досвідчені користувачі».

Після складання переліку кіл користувачів для конкретної системи наступним кроком є визначання завдань, які належить виконувати кожному колу користувачів. І знову це часто по­дають у вигляді ієрархії, як показано на рисунку D.2.

Ієрархія завдань для кола користувачів «Оператори з вводу даних»

Рисунок D.2 — Ієрархія завдань

Наступний крок полягає у визначанні наявних інформаційних потреб стосовно кожного пев­ного кола користувачів та завдання. Цей перелік інформаційних потреб формує базу щодо змісту документа, як показано на рисунку D.3.

Інформаційні потреби
для кола користувачів «Оператор даних»
щодо завдання «Формування пакета»

• Використовування клавіатури (передбачувані знання)

• Як увійти до системи

• Який екран використовувати для формування пакета — Як завершити роботу з екраном

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

На цьому етапі (але, загалом, не перед цим) можна визначити носії для постачання та тип документа.Наприклад, для конкретної інформаційної потреби для певного завдання найприйнятнішим форматом документа може бути друкована настанова, або екран контекстно-залежної довідки, або шпалери, або,,навіть, відео чи короткий довідник.

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

На рисунку D.4 показано процес від початку до кінця. Одним із важливих аспектів є те, що знання, яких потребує користувач, розподілено по різних носіях; діалогова або паперова доку­ментація не має наперед визначеної ролі — роль будь-якого носія полягає у перенесенні всього того знання користувача, яке підходить до цього носія залежно від кола користувачів, продукту та набору завдань, яких це стосується. Планування розроблення документації (як наведено у цьому стандарті) стосується, головним чином, визначання потрібних знань, і тільки наприкінці процесу постає питання щодо вибору носія. Таким чином, паперову та діалогову документацію треба планувати разом, тому що один і той самий користувач може потребувати обидва типи документації для задоволення його потреби в частині різних аспектів потрібних йому знань.

Перелік кіл користувачів

Перелік завдань для кожного кола користувачів

Необхідні знання для кожного завдання для кожного кола користувачів

Рисунок D.4 — Зведений процес

Детальний опис цього процесу надано у британському стандарті BS 7649:1993 Guide to the design and preparation of documentation for users of application software (Настанова щодо розроб­лення та підготовлення документації для користувачів прикладного програмного забезпечення).ДОДАТОК Е
(довідковий)

ДОКУМЕНТУВАННЯ УКРАЇНСЬКОЮ МОВОЮ

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

Треба застосовувати таку термінологію:

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

2. Треба створити глосарії, які охоплюють таке:

1. визначання всіх специфічних щодо продукту та незнайомих термінів;

2. розширені форми та визначення всіх абревіатур та скорочень;

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

4. бібліографію спеціалізованих словників та міжнародних стандартів.

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

4. Кожна абревіатура має бути визначена під час першого застосування в основній частині тексту.

5. Кожний термін треба використовувати послідовно в межах документа, діалогової інфор­мації та системної бібліотеки.

6. Складені фрази на зразок «картковий увід» повинні мати тільки одне значення, яке тре­ба використовувати послідовно.

д) Складені фрази треба обмежувати трьома словами.

8. Одне й те саме слово не треба використовувати для різних частин мови.

9. Всі специфічні щодо продукту та спеціалізовані терміни треба вводити в рамках поясню­вального або самодостатнього контексту.

10. Терміни, введені без достатнього контексту на зразок написів на клавіатурі або команд, треба визначити в глосарії.

11. Треба уникати застосовування слів на зразок «більон».

Примітка. Більон США (= 1 000 000 000) не те саме, що старий більон у Великій Британії (= 1 000 000 000 000).

І) Використовування терміна «переведення» для згадування, наприклад переведення фор­мату файла треба уникати; замість цього треба вживати термін «перетворення».

Е.З Стиль перекладу

Треба використовувати тільки широко вживані абревіатури, які треба пояснити у списку абревіатур. Треба уникати такого:

1. Символа США для фунта (#).

2. Крапки як знака множення.

Авторам документів треба остерігатися таких слів, що дезорієнтують читача:

1. хто, що, який;

2. тільки, попросту, просто, головним чином, легко;

3. хоча;

4. таким чином;

5. як;

6. може, може бути;

д) потім;

8. коли, якщо;

Треба звернути увагу на такі аспекти синтаксису:

1. Речення не-повинні бути занадто довгими.

2. Треба уникати конструкції речення, що містить послідовності понять, розділені комами.

3. Треба чітко розрізняти обмежувальні та не обмежувальні умови.

Не треба застосовувати тире там, де можна використати дужки або крапку з комою.

Треба звернути увагу на такі фізичні фактори:

1. Не треба застосовувати абревіатури з ціллю економії місця.

2. Треба залишати достатньо місця, наприклад для грошових значень.

3. Треба застосовувати стандартні графічні засоби й уникати надзвичайних технологій.

4. Треба уникати вбудовування тексту в ілюстрації.

5. Треба використовувати графічні загальновизнані символи.

6. Там, де це можливо, треба заміняти слова графікою.

Треба звернути увагу на такі аспекти стосовно діалогової інформації:

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

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

3. Програмне забезпечення не повинно залежати від довжини, формату або положення вхідних та вихідних полів.

4. Для кожної ідеї треба використовувати окреме повідомлення. Повідомлення не повинні конструюватися.

5. Змінні повідомлень повинні містити тільки інформацію, що не перекладається, на зра­зок ключових слів та кодів вернення.

6. Не треба опускати прийменники у реченнях з ціллю економії місця.

Треба звернути увагу на такі культурні чинники:

1. Зображення (на зразок облич, тварин та телефонів) мають бути культурно нейтральними.

2. Треба уникати прикладів, специфічних щодо місцевої культури або місцевих особливо­стей ведення справ (свята, банківські послуги, заробітна плата, спорт тощо).

3. Треба уникати ідіоматичних виразів, специфічних для національної мови постачальни­ка документації, у тексті та зображеннях.

4. Треба уникати гумору, особливо каламбурів та гри слів.

5. Іронію треба вживати обережно.

6. Треба уникати сленгу, жаргону та розмовних слів.

д) Не треба вживати першу особу.

8. Не треба позначати дати у суто цифровій формі. Обов’язково треба завжди виписувати назву місяця (наприклад, 26 липня 1991).

9. Треба застосовувати двовимірність, за винятком випадків, коли міжнародні угоди дикту­ють протилежне — наприклад розміри шин, водяні труби, цвяхи та фотоплівка.

Коли наявні метричні вимірювання разом іншими вимірюваннями, треба пояснити значення.ДОДАТОК F
(довідковий)

ОЦІНЮВАННЯ

F.1 Загальні положення

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

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

F.2 Метод «Хвилини та години»

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

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

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