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

 

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

·  Документи управління розробкою ПЗ.

·  Документи, що входять до складу ПЗ.

Документи управління розробкою ПЗ керують і протоколюють процеси розробки і супроводу ПЗ, забезпечуючи зв'язок усередині колективу розроблювачів ПЗ і між колективом розроблювачів і менеджерами ПЗ - особами, що керують розробкою ПЗ. Ці документи можуть бути наступних типів:

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

· Звіти про використання ресурсів у процесі розробки. Створюютьсяменеджерами.

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

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

· Замітки і переписування. Ці документи фіксують різні деталі взаємодії між менеджерами і розроблювачами.

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

·  Користувальницька документація ПЗ (К-документація).

·  Документація по супроводу ПЗ (С-документація).

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

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

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

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

Внутрішня –це коментарі, вся решта документація – зовнішня.

Документація програмного засобу може бути в паперовому та безпаперовому вигляді.

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

 

-2-

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

У зв'язку з цим варто розрізняти дві категорії користувачів ПЗ: ординарних користувачів ПЗ і адміністраторів ПЗ. Ординарний користувач ПЗ використовує ПЗ для рішення своїх задач (у своїй предметній області). Це може бути інженер, що проектує технічний пристрій, чи касир, що продає залізничні квитки за допомогою ПЗ. Він може і не знати багатьох деталей роботи комп'ютера чи принципів програмування. Адміністратор ПЗ керує використанням ПЗ, ординарними користувачами і здійснює супровід ПЗ, не зв'язаний з модифікацією програм. Наприклад, він може регулювати права доступу до ПЗ між ординарними користувачами, підтримувати зв'язок з постачальниками ПЗ чи виконувати визначені дії, щоб підтримувати ПЗ у робочому стані, якщо воно включено як частина у інші систем.

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

Можна вважати типовим наступний склад користувальницької документації для досить великих ПЗ:

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

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

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

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

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

Складання документації для користувачів має свої особливості, пов'язані з тим, що користувач, як правило, не є професіоналом в області розробки програмного забезпечення. У книзі С. Дж. Грімм [17] дані рекомендації по написанню подібної програмної документації:

• враховуйте інтереси користувачів - керівництво повинне містити всі інструкції, необхідні користувачеві;

• викладайте ясно, використовуйте короткі пропозиції;

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

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

• загальні відомості про програмний продукт;

• опис установки;

• опис запуску;

• інструкції по роботі (або опис призначеного для користувача інтерфейсу);

• повідомлення користувача.

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

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

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

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

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

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

 

-3-

 

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

Документацію по супроводу ПЗ можна розбити на дві групи:

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

- документацію, що допомагає вносити зміни в ПЗ.

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

·  Зовнішній опис ПЗ.

·  Опис архітектури ПЗ.

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

·  Тексти модулів обраною мовою програмування.

Пояснювальна записка повинна містити всю інформацію, необхідну для супроводу і модифікації програмного забезпечення: відомості про його структуру і конкретних компонентах, загальний опис алгоритмів і їх схеми, а також обгрунтування прийнятих технічних і техніко-економічних рішень. Вміст пояснювальної записки за стандартом (ГОСТ 19.404-79) повинен виглядати таким чином:

• введення;

• призначення і сфера застосування;

• технічні характеристики;

• очікувані техніко-економічні показники;

• джерела, використовувані при розробці.

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

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

Розділ Технічні характеристики повинен містити наступні підрозділи:

• постановка завдання, опис вживаних математичних методів і допущень і допущень і обмежень, пов'язаних з вибраним математичним апаратом;

• опис алгоритмів і функціонування програми з обгрунтуванням прийнятих рішень;

• опис і обгрунтування вибору способу організації вхідних і вихідних даних;

• опис і обгрунтування вибору складу технічних і програмних засобів на підставі проведених розрахунків або аналізів.

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

Документація другої групи містить

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