Страница 2: ДСТУ 4302:2004. Інформаційні технології. Настанови щодо документування комп’ютерних програм (61990)

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

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

• Інформаційні елементи рівня 1 можуть потребуватися у підсумкових документах або на ранніх етапах життєвого циклу. Інформаційні елементи рівнів 1 та 2 можуть потребуватись в детальніших документах або на пізніших етапах життєвого циклу.

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

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

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

Для укладання профілю документації треба виконати такі дії:

І Визначити, які документи необхідні протягом життєвого циклу. Назви цих документів по­винні бути перелічені вздовж вершин стовпчиків профілю документації (стовпчики з 4-го до л-го).

ІІ Переглянути вміст кожного інформаційного елемента для визначання того, чи він потрібен у цьому документі. Визначити, чи є інформація суттєвою (С), обумовленою (О) або необов’язко­вою (Н).

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

Рекомендовано пояснювати вміст за допомогою прикладів.

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

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

Цей стандарт можна також використовувати для перегляду документів із наявного комплекту документації для встановлювання факту їх узгодженості з цим стандартом.

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

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

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

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

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

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

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

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

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

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

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

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

4.5 Пристосування

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

5 МЕТОД ДОКУМЕНТУВАННЯ

Загальний вигляд опису подано як перелік деревовидної структури (рисунок 1). Перелік містить назви та номери інформаційних елементів, деталізованих у описі інформаційних елементів (5.3 та 5.4).

Номери та назви елементів, що їх показано під заголовком «Структура», є заголовками групи та підгрупи для інформаційних елементів, що визначають конкретну інформацію.

Форму профілю документації (рисунок 2) подано у вигляді шаблону для створювання про­філю документації для програмної системи.

У профілі документації матрицю поділено на ряд стовпчиків. Кожен документ, потрібний для програми, представлено стовпчиком (наприклад, А, В, С). Додаток А слугує прикладом того, як ідентифікувати документи, зображені на рисунку 2.

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

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

Угода щодо нумерування має такий вигляд:

• Кожен заголовок має номер для зазначання його положення в підпорядкованості (рисунки 1 та 3).

• Кожен інформаційний елемент має номер елемента, який може складатися щонайбільше із чотирьох цифр (рисунок 1).

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

Інформаційні елементи групують та позначають за допомогою заголовків. Заголовок містить номер, що відповідає його місцю у структурі. Наступний номер є назвою групи (може містити короткий опис — рисунок 4).

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

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

ІІ Складений інформаційний елемент містить номер піделемента, кожен з яких містить но­мер, назву елемента та вміст елемента. Складений інформаційний елемент може, таким чином, застосовуватися у документі на різних рівнях деталізації. Рівень деталізації у складеного інформа­ційного елемента виражається за допомогою комбінування піделементів відповідно до потрібного рівня (рисунки 4, 5 та 6). У цьому стандарті складений інформаційний елемент має два або три рівні деталізації (рисунок 4).

Затінені стовпчики на рисунках 4, 5 та 6 вказують на відсутність подальших рівнів деталі­зації. В цьому випадку потрібні деталі можуть бути подані на рівні 1 або рівні 2.

Стовпчики (рівня 1, рівня 2 або рівня 3) вказують на рівень деталізації. Для складеного інфор­маційного елемента рівень 2 містить всі піделементи з рівня 1 та деякі додаткові піделементи. Аналогічно, рівень 3 містить всі піделементи з рівня 2 та всі піделементи, що залишились для цього складеного інформаційного елемента.

Це означає, що (рисунки 4 та 6):

• Інформаційні елементи рівня 1 містять всі піделементи, назва інформаційного елемента яких є «рівень 1».

• Інформаційні елементи рівня 2 містять всі піделементи, назва інформаційного елемента яких є «рівень 2».

• Інформаційні елементи рівня 3 містять всі піделементи, назва інформаційного елемента яких є «рівень 3».

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

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

Коли назву піделемента застосовують впродовж двох або більше рівнів (наприклад, 212.1 Назва цілі), значення піделемента може бути тим самим, що і на всіх рівнях, або може бути, за потреби, розширено на рівні 2 та рівні 3.

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