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

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

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

План документування має охоплювати (але не обмежувати) таке:

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

2. Специфікацію стилю, як встановлено в 8.2.

3. Визначення кола користувачів (див. 8.1.3.2).

4. Аргументи, з яких визначене коло користувачів буде використовувати документацію та з якою ціллю.

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

6. Елементи постачання: кількість друкованих копій, зазначення того, чи будуть надавати­ся електронні копії; дискові та файлові формати (охоплюючи версії програмного забезпечення); зазначення того, куди саме вони будуть постачатися.

д) Умови володіння авторськими правами та будь-якими іншими правами власності.

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

8. Заходи, які треба вжити для перекладу документації на інші мови.

Примітка. Настанову дивись у додатку Е щодо Грунтовнішої інформації

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

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

10. Методи, засоби та версії засобів продукування, що мають застосовувати.

1. Структура групи, в рамках якої буде працювати персонал з розроблення документації; додатково — план підбирання групи.

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

т) Проектні залежності.

8. Трудомісткість (людино-години) та вартість, потрібні для розроблення документації (дивись додаток F щодо настанови з оцінювання).

15. Вимоги щодо проектних ресурсів, охоплюючи інформацію та інші ресурси, що надає замовник, та терміни їх надання.

16. Метод передавання інформації у разі зміни програмного забезпечення під час розроб­лення програмного забезпечення.

17. Плани щодо керування змінами та супроводження документації (за потреби).

г) Плани післяреалізаційного переглядання (за потреби).

s) Календарний план, що демонструє відповідні контрольні точки, охоплюючи, за потреби, такі:

1. затвердження плану документування;

2. підготовлення, переглядання та коригування кожної попередньої версії',

3. тестування придатності;

4. підготовлений художніх робіт щодо оригінал-макета;

5. друк, переплетення та розподілення.

Коли це прийнятно, кожен із цих елементів може бути повторено для кожної складової частини документації

Примітка 1. Іноді корисно долучати до плану документування приклади щодо подібної документації, створеної постачальником документації, або навіть приклади документації, створеної іншими, щоб означити передбачуваний стиль або макет, або те й інше

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

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

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

Примітка 1. Дані для визначення кола користувачів можна отримати з наступних джерел

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

2. визначень, наданих замовником,

3. визначень кіл користувачів, отриманих з інших джерел

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

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

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

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

Примітка. Ціль перегляду — впевнитись у тому, що надіслані матеріали є повними та коректними та що вони відпо­відають потребам замовника, як визначено у контракті та плані документування

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

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

Замовник перед затвердженням кожної попередньої версії документації повинен впевнитися в тому, що аспекти, пов’язані з захистом та юридичні аспекти документації, враховано належ­ним чином.

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

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

Примітка 2. Якщо запитувані зміни виходять за рамки контракту та плану документування, може знадобитися внесення змін до контракту

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

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

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

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

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

Настійно рекомендовано застосовування засобів порівняння документів для генерування позначок, що вносять під час переглядання, якщо такі засоби наявні

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

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

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

3. У другій попередній версії позначки переглядання з номером «1» треба використовувати для зазначення тих місць, у яких зміни було внесено в результаті переглядання першої попередньої версії.

4. У третій попередній версії позначки переглядання з номером «2» треба використовувати для зазначення змін е) Після прийняття третьої попередньої версії всі позначки, що вносять під час переглядання, треба видалити до того, як публікацію буде передано на переглядання коректури.

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

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

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

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

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

Примітка 1. Перед постачанням першу попередню версію треба відредагувати Для цього є дві підстави'

1. це гарантує, що учасники переглядання не відволікаються на коригування типографських та компонувальних помилок;

2. це гарантує, що будь-які технічні неточності, спричинені процесом редагування, будуть виявлені учасниками переглядання

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

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