ДСТУ ISO/IEC 15910:2012 Информационные технологии. Документирование программ. Документация пользователя (ISO/IEC 15910:1999, IDT)

НАЦІОНАЛЬНИЙ СТАНДАРТ УКРАЇНИ

Інформаційні технології
ДОКУМЕНТУВАННЯ ПРОГРАМ ДОКУМЕНТАЦІЯ КОРИСТУВАЧА

(ISO/ІЕС 15910:1999, IDT)
ДСТУ ISO/ІЕС 15910:2012

 

Київ
МІНЕКОНОМРОЗВИТКУ УКРАЇНИ
2013

ПЕРЕДМОВА

1 ВНЕСЕНО: Технічний комітет стандартизації «Інформаційні технології» (ТК 20) та Інститут програмних систем Національної Академії наук України

ПЕРЕКЛАД І НАУКОВО-ТЕХНІЧНЕ РЕДАГУВАННЯ: П. Андон, академік НАНУ; Л. Бабко; В. Кириленко; В. Неумоін, канд. техн. наук

2 НАДАНО ЧИННОСТІ: наказ Мінекономрозвитку України від 28 листопада 2012 р. № 1356 з 2013-07-01

3 Національний стандарт відповідає ISO/IEC 15910:1999 Information technology – Software user documentation process (Інформаційні технології. Процес документування програм користувача)

Ступінь відповідності – ідентичний (IDT)

Переклад з англійської (en)

4 УВЕДЕНО ВПЕРШЕ

ЗМІСТ

Національний вступ

Вступ до ISO/ІЕС 15910:1999

1 Сфера застосування

2 Відповідність

3 Нормативні посилання

4 Терміни та визначення понять

5 Керування якістю

6 Застосування

7 Ціль

8 Вимоги

8.1 Процес документування

8.1.1 Загальні положення

8.1.2 Надання вихідних матеріалів

8.1.3 План документування

8.1.4 Переглядання

8.1.5 Тестування придатності документації

8.1.6 Розроблення документації із залученням інших компаній-субпідрядників

8.1.7 Керування змінами та супровід документації

8.2 Зміст специфікації стилю

8.2.1 Загальні положення

8.2.2 Стиль написання

8.2.3 Паперова документація

8.2.4 Електронна документація

Додаток А Перехресні посилання на ISO/ІЕС 12207

Додаток В Звернення до цього стандарту у контракті

Додаток С Приклад плану документування: документація користувача для системи керування плівками АВС

Додаток D Взаємозалежність між колом користувачів, завданнями, паперовою та діалоговою інформацією

Додаток Е Документування українською мовою

Додаток F Оцінювання

Додаток G Оцінювання плану документування

Додаток Н Приклад специфікації стилю

Бібліографія

НАЦІОНАЛЬНИЙ ВСТУП

Цей стандарт є письмовий переклад ISO/IEC 15910:1999 Information technology – Software user documentation process (Інформаційні технології. Документування програм. Процес документування програм користувача).

Технічний комітет, відповідальний за цей стандарт в Україні, – ТК 20 «Інформаційні технології».

Стандарт містить вимоги, які відповідають чинному законодавству України.

До цього стандарту внесено такі редакційні зміни:

— структурні елементи стандарту: «Титульний аркуш», «Передмову», «Національний вступ», першу сторінку, «Терміни та визначення понять» та «Бібліографічні дані» – оформлено згідно з вимогами комплексу стандартів «Національна стандартизація»;

— вилучено «Предметний покажчик» через суттєву різницю між англійськими та українськими термінами;

— назву додатка Е «Написання документів англійською мовою для перекладу» замінено на «Документування українською мовою»;

— з «Передмови» до ISO/IEC 15910:1999 у цей «Національний вступ» долучено те, що стосується цього стандарту;

— у розділі «Нормативні посилання» та «Бібліографії» наведено «Національні пояснення», виділені в тексті рамкою.

Додатки А–Н – довідкові.

У тексті стандарту містяться посилання на міжнародні стандарти, яким відповідають такі національні стандарти України:

ДСТУ ISO/IEC 6592:2004 Інформаційні технології. Настанови щодо документування комп’ютерних програм (ISO/IEC 6592:2000, MOD).

ДСТУ ISO/IEC 12119:2003 Інформаційні технології. Пакети програм. Тестування і вимоги до якості (ISO/IEC 12119:1994, IDT).

ДСТУ 3918-99 Інформаційні технології. Процеси життєвого циклу програмного забезпечення (ISO/IEC 12207:1995, IDT).

Копії міжнародних стандартів, на які є посилання у цьому стандарті, можна замовити в Головному фонді нормативних документів.

ВСТУП до ISO/IEC 15910:1999

Існує два види стандартів:

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

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

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

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

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

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

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

Цей міжнародний стандарт було підготовлено об’єднаним технічним комітетом ISO/ІЕС ЛС 1 на основі австралійського стандарту АБ 4258:1994. Щодо відповідності між ISO/ІЕС 12207:1995 та цим міжнародним стандартом дивіться додаток А.

НАЦІОНАЛЬНИЙ СТАНДАРТ УКРАЇНИ

ІНФОРМАЦІЙНІ ТЕХНОЛОГІЇ
ДОКУМЕНТУВАННЯ ПРОГРАМ ДОКУМЕНТАЦІЯ КОРИСТУВАЧА

ИНФОРМАЦИОННЫЕ ТЕХНОЛОГИИ
ДОКУМЕНТИРОВАНИЕ ПРОГРАММ ДОКУМЕНТАЦИЯ ПОЛЬЗОВАТЕЛЯ

INFORMATION TECHNOLOGY
SOFTWARE USER DOCUMENTATION PROCESS

Чинний з 2013-07-01

1 СФЕРА ЗАСТОСУВАННЯ

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

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

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

Цей стандарт призначено для використовування виробниками та покупцями документації користувача.

Цей стандарт застосовний не тільки до друкованої документації, а також і до екранів довідки, систем надання допомоги та оперативних текстових систем та систем надання допомоги. Дивись структурний елемент «Бібліографія».

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

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

2 ВІДПОВІДНІСТЬ

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

3 НОРМАТИВНІ ПОСИЛАННЯ

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

ISO/IEC 216:1975 Writing paper and certain classes of printed matter – Trimmed sizes – A and В series.

НАЦІОНАЛЬНЕ ПОЯСНЕННЯ

ISO/IEC 216:1975 Папір для писання та деякі класи друкованих матеріалів. Формати обраної паперової смуги. Серії А та В.

4 ТЕРМІНИ ТА ВИЗНАЧЕННЯ ПОНЯТЬ

З огляду на призначення цього стандарту вжито такі терміни та визначення позначених ними понять:

4.1 А4, А5

Встановлені цим стандартом розміри паперу, А4: 297 мм х 210 мм та А5: 210 х 148 мм; див. ISO 216:1975

4.2 замовник (acquirer)

Організація, що замовляє або дістає систему, програмний продукт чи послугу від постачальника. [ISO/IEC 12207:1995, визначення наведене в 3.1].

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

4.3 коло користувачів (audience)

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

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

4.4 досліджування кола користувачів (audience research)

Спланований процес проведення інтерв’ю, а також аналізування результатів інтерв’ю та даних щодо персоналу.

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

4.5 В5

Встановлені міжнародним стандартом розміри паперу: 176 мм х 250 мм; див. ISO 216:1975

4.6 кінцеві матеріали (back matter)

Матеріали, що з’являються наприкінці книги або настанови на зразок індексу

4.7 оригінал-макети (camera-ready originals)

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

4.8 крайній термін (cut-off date)

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

4.9 одиниці постачання (deliverables)

Елементи, постачання яких замовнику обумовлено контрактом

4.10 документ (document)

Те саме, що елемент документації

4.11 документація (documentation)

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

4.12 персонал з розробляння документації (documentation development staff)

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

Примітка. До персоналу належать автори, дизайнери, ілюстратори та керівництво проекту

4.13 план документування (documentation plan)

Документ, що встановлює основні елементи проекту документування

4.14 постачальник документації (documenter)

Сторона, що готує документацію

Примітка. Термін розробник (як визначено в ISO/IEC 12207:1995, наведено у визначенні 3.31) тут не застосовний, тому що стосовно документації розробник програмного забезпечення часто виступає замовником документації, й використовування терміна «розробник» може вносити плутанину у цьому контексті. Отже вжито термін «постачальник документації»

4.15 електронна копія (electronic copy)

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

4.16 коротке тире (en dash)

Тире такої самої ширини, як прописна літера «н»

4.17 кінцеві виноски (endnotes)

Примітки, зібрані наприкінці розділу або документа

4.18 сфальцьована вклейка (foldout)

Окрема сторінка, ширша за решту, зазвичай складена так, щоб не було потреби її обрізати

4.19 нижній колонтитул (footer)

Матеріал, що повторюється внизу кожної сторінки (наприклад номер сторінки)

4.20 виноска (footnote)

Текст внизу сторінки, зазвичай меншого шрифту, на який є посилання у вигляді номера або іншої позначки в тексті тієї самої сторінки

БІБЛІОГРАФІЯ

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

Споріднені національні та міжнародні стандарти

1 ISO 6592 Information technology – Guidelines for the documentation of computer-based application systems.

2 ISO 9127:1988 Information processing systems – User documentation and cover information for consumer software packages.

3 ISO/IEC 12119:1994 Information technology – Software packages – Quality requirements and testing.

4 ISO/IEC 12207:1995 Information technology – Software life cycle process.

5 BS 7649:1993 The design and preparation of documentation for users of application software.

Загальні публікації

6 Barnum C. M. and Carliner S. Techniques for Technical Communicators, MacMillan, 1993.

7 Brockmann, R. J. Writing Better Computer User Documentation. Wiley, 1990.

8 Brusaw C. T., Aired G. J. and Oliu W. E. Handbook of Technical Writing, St. Martin’s Press, 1993.

9 Burnett R. E. Technical Communications, Wadsworth Publishing, 1994.

10 Hackos J. T. Managing Your Documentation Projects, Wiley, 1994.

11 Holtz H. The Complete Guide to Writing Readable User Manuals. Dow Jones-lrwin, 1988.

12 Horton W. K. Illustrating Computer Documentation. Wiley, 1991.

13 Simpson H. and Casey S. M. Developing Effective User Documentation: A Human Factors Approach. McGraw-Hill, 1988.

14 Weiss E. H. How to Write Usable User Documentation, Oryx Press, 1991.

15 Zinsser W. On Writing Well, Harper and Row, 1994.

Діалогова документація та гіпертекст

16 Bogan S., Farkas D. and Wellinske J. Developing On-Line Help for Windows, International Thomson Press, 1995.

17 Brown C. M. Human-Computer Interface Design. Norwood, 1988.

18 Helander (Ed). Handbook of Human-Computer Interaction. North Holland.

19 Horton W. K. Designing and Writing On-line Documentation. Help Text to Hypertext. Wiley, 1990.

20 Horton W. K. Designing and Writing On-line Documentation: Hypermedia for Self-Supporting Products, Wiley, 1994.

21 Laurel and Mountford The Art of Human-Computer Interface Design. Addison-Wesley, 1990.

22 Van der Veer and Mulder Human-Computer Interaction. Springer-Verlag, 1988.

Тестування на придатність

23 Dumas J. S. and Redish J. C. A Practical Guide to Usability Testing, Ablex Publishing, 1993.

24 Nielson J. Usability Engineering, AP Professional, 1993.

НАЦІОНАЛЬНЕ ПОЯСНЕННЯ

Споріднені національні та міжнародні стандарти

1 ISO 6592 Інформаційні технології. Настанови щодо документування комп’ютерних програм.

2 ISO 9127:1988 Системи обробляння інформації. Документація користувача та інформація на обкладинках пакетів програмного забезпечення споживача.

3 ISO/IEC 12119:1994 Інформаційні технології. Програмні пакети. Тестування і вимоги щодо якості.

4 ISO/IEC 12207:1995 Інформаційні технології. Процеси життєвого циклу програмного забезпечення.

5 BS 7649:1993 Розроблення та підготовлення документації для користувачів прикладного програмного забезпечення.

Загальні публікації

6 Барнум К. М. (Barnum С. М.) та Карлінер С. (Carliner S.) Методи технічної комунікації, MacMillan,. 1993.

7 Брокман Р. Д. (Brockmann, R. J.) Написання кращої документації для користувачів комп’ютерів. Wiley, 1990.

8 Брусау К. Т. (Brusaw С. Т)., Елред Дж.Дж. (Aired G. J.) та Олью В.Е. (Oliu W. Е.) Довідник із написання технічних текстів, St. Martin’s Press, 1993.

9 Барнет P. Е. (Burnett R. E.) Технічна комунікація, Wadsworth Publishing, 1994.

10 Хекос Дж. T. (Hackos J. T.) Керування вашими проектами документування, Wiley, 1994.

11 Хольтц Г. (Holtz H.) Повна настанова щодо написання придатних для читання настанов для користувача. Dow Jones-lrwin, 1988.

12 Хортон В. К. (Horton W. К.) Ілюстрування комп’ютерної документації. Wiley, 1991.

13 Сімпсон Г. (Simpson Н.) та Кайзі С. М. (Casey S. М.) Розробляння ефективної документації для користувачів: Підхід на основі людського чинника. McGraw-Hill, 1988.

14 Вайсс Е. Г. (Weiss Е. Н.) Як писати придатну документацію для користувачів, Oryx Press, 1991.

15 Цінссер В. (Zinsser W.) Про те, як писати добре, Harper and Row, 1994.

Діалогова документація та гіпертекст

16 Боган С. (Bogan S.), Фаркас Д. (Farkas D.) та Веллінске Дж. (Wellinske J.) Розроблення діалогової довідкової системи для Windows, International Thomson Press, 1995.

17 Броун К. М. (Brown, С. М.) Розроблення інтерфейсу «людина-комп’ютер». Norwood, 1988.

18 Хеландер (ред.) (Helander) Настанова щодо взаємодії «людина-комп’ютер». North Holland.

19 Нортон В. К. (Horton W. К.) Розроблення та написання діалогової документації: Від підказки до гіпертексту. Wiley, 1990.

20 Нортон В. К. (Horton W. К.) Розроблення та написання діалогової документації: Гіперсередовище для продуктів самопідтримкою, Wiley, 1994.

21 Лаурел та Моунтфорд (Laurel and Mountford) Мистецтво розроблення інтерфейсу «людина-комп’ютер». Addison-Wesley, 1990.

22 Ван дер Beep та Малдер (Van der Veer and Mulder) Взаємодія «людина-комп’ютер». Springer-Verlag, 1988.

Тестування на придатність

23 Дюма Д. С. (Dumas J. S.) та Редіш Д. К (Redish J. С.) Практична настанова щодо тестування на придатність, Ablex Publishing, 1993.

24 Нілсон Дж. (Nielson J.) Інженерія придатності, АР Professional, 1993.