6

На початку було Слово.

Біблія, Новий заповіт

Від Іоанна святе благовествование

Лекція 13

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

13.1. Документація, що створюється і використовувана в процесі розробки програмних засобів.

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

Цю документацію можна розбити на дві групи [13.1]:

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

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

Документи управління розробкою ПС (software process documentation) управляють і протоколюють процеси розробки і супроводу ПС, забезпечуючи зв'язки усередині колективу розробників ПС і між колективом розробників і менеджерами ПС (software managers)  особами, керівниками розробкою ПС. Ці документи можуть бути наступних типів [13.1]:

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

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

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

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

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

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

• Призначена для користувача документація ПС (П-документация).

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

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

Призначена для користувача документація ПС (user documentation) пояснює користувачам, як вони повинні діяти, щоб застосувати ПС, що розробляється [13.1, 13.2.]. Вона необхідна, якщо ПС припускає яку-небудь взаємодію з користувачами. До такої документації відносяться документи, якими повинен керуватися користувач при інсталяції ПС (при установці ПС з відповідним настроюванням на середовище застосування ПС), при застосуванні ПС для вирішення своїх завдань і при управлінні ПС (наприклад, коли ПС, що розробляється, взаємодіятиме з іншими системами). Ці документи частково піднімають питання супроводу ПС, але не стосуються питань, пов'язаних з модифікацією програм.

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

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

Відповідно до робіт [13.1, 13.2] можна вважати типовим наступний склад призначеної для користувача документації для достатньо великих ПС:

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

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

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

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

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

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