Розробка документації на програмне забезпечення

Лабораторна робота № 6

Міністерство Освіти і Науки України

Національний університет “Львівська політехніка”

Кафедра автоматизованих систем управління

Методичні вказівки

до лабораторної роботи № 6

“Розробка документації на програмне забезпечення”

з дисципліни

“Технологія програмування та створення програмних продуктів”

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

“Комп’ютерні науки” (шифр 0804)

Львів-2009

Методичні вказівки до лабораторної роботи № 6 “Розробка документації на програмне забезпечення” з дисципліни “Технологія програмування та створення програмних продуктів” для студентів спеціальності - шифр 0804 “Комп’ютерні науки”/ Укл. доц. Ковівчак Я.В.,

Львів: Національний університет “Львівська політехніка”, 2009.

Методичні вказівки обговорено та схвалено на засіданні кафедри АСУ Протокол № ___________ від «___»___________2009 р.

Завідувач кафедрою АСУ ______________ Рашкевич Ю. М.

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

Протокол № ___________ від «___»___________2009 р.

Лабораторна робота № 6

Розробка документації на програмне забезпечення

Мета: Ознайомитись з етапом виготовлення документації на програмний продукт.

Завдання: Розробити необхідний повний перелік документації на програмне забезпечення.

1. Теоретична Частина

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

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

Документація проекту

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

• Плани, оцінки, графіки роботи - документи, розроблені менеджерами.

• Схвалені документи - це інструкції для виробників.

• Звіти - документи, підготовані супервізорами. Ці документи описують роботу і її результати.

• Стандарти - документи, що описують необхідні стандарти.

• Робочі документи - різноманітні документи з ідеями рішень. Автори можуть бути членами команди. Якщо їх схвалять, ці документи можуть стати стандартами.

• Повідомлення - примітки, коментарі, які використовуються для комунікації між членами команди.

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

• інформація про усі версії,

• інформація про клієнтів і версії, які вони придбали,

• ПЗ і апаратні вимоги до версії,

• інформація про компоненти (класи, об'єкти, модулі), потрібні для версії,

• інформація про можливі зміни версії,

• інформація про виявлені помилки.

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

До уваги повинні бути взяті наступні пункти:

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

• номери послідовності і опис повинні містити:

• тип документа,

• номер документа,

• номер версії,

• дата версії,

• стан;

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

• процедури введення змін; призначення відповідальних;

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

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

Інфраструктура звіту

Управління проектом вимагає підготовки детальної документації і відповідності крайнім термінам. Керівники проекту підготовлюють звіти клієнтам - ініціаторам проекту і супервізорам вищого рангу. Звіти є дуже важливі для продуктивності проекту. Звіти обговорюються на зустрічах. Необхідно робити звіти про прогрес і час завантаження працівників. Формальні звіти повинні супроводжуватися особистим спілкуванням з персоналом.

Звіти стану роботи

Регулярно (наприклад, щомісячно) керівництво повинно організовувати зустрічі, для яких повинні готуватися звіти про наступні теми:

• технічний стан,

• стан ресурсів,

• проходження графіку,

• проблеми,

• фінансовий стан.

Часові таблиці

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

Технічна документація

Таку документацію часто включають безпосередньо у вихідний код або надають разом з ним.

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

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

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

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

Генератори можна умовно розділити на:

— Універсальні

-Doxygen для C, Java, Python, PHP. На виході - html, pdf, man, pdf, rtf.

-NaturalDocs

-AsciDoc

-doc-o-matic для Matlab, ASPX, JSP, IDL, Delphi, C#, VB, Java, PHP

— Специфічні

-javadoc для Java

-phpDocumentor для PHP

-docutils NDoc, Sandcastle,

-GhostDoc для .NET

-pasdoc для Delphi

-ZenDoc для ActionScript

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

Технічна документація повинна бути перевірена перед тим, як ПЗ буде доставлене клієнтові.

Архітектурна / проектна документація

Проектна документація зазвичай описує продукт у загальних рисах. Вона відповідає на питання «чому саме так?» Наприклад, у проектному документі програміст може описати обґрунтування того, чому структури даних організовані саме таким чином.

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

Користувацька документація

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

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

Документація повинна бути написана простою, доступною мовою, особливо, якщо ця документація призначена для користувачів персональних комп’ютерів. Дуже важливо, щоб документація не вводила в оману і була актуальною. Інструкція повинна мати чітку структуру; логічна зв’язаність і простота також мають велике значення.

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

Маркетингова документація

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

1. підігріти інтерес до продукту у потенційних користувачів

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

3. пояснити положення продукту в порівнянні з конкуруючими рішеннями

Однією з гарних маркетингових практик є впровадження слогана - простої фрази, що запам'ятовується; вона ілюструє те, що ми прагнемо донести до користувача, характеризує відчуття, які створює продукт.

Часто буває так, що коробка продукту та інші маркетингові матеріали дають більш ясну картину про можливості та способи використання програми, ніж все інше.

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

Документація на етапах розробки ПЗ

Етап визначення вимог

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

Приклад такого документа:

Таблиця 1. Приклад документа з вимогами.

План Тіло документу Стандарт: ANSI/IEEE std 830-1993 Рекомендований порядок специфікації вимог програмного забезпечення	Резюме (не більше 200 слів) Зміст Статус документу: автори, компанії, дати і т.д. Зміни, зроблені після останньої версії
	1.  Вступ 1.1 Ціль 1.2 Контекст 1.3 Визначення, скорочення, абревіатури 1.4 Посилання 1.5 Короткий огляд 2.  Загальний опис 2.1 Зручність роботи з програмою 2.2 Загальні характеристики 2.3 Характеристики користувача 2.4 Умови роботи 2.5 Припущення та взаємозв'язки 3.  Вимоги 3.1 Функціональні вимоги 3.2 Нефункціональні вимоги 4. Доповнення

Послідовність дій, необхідних для оформлення документа, повинна бути наступною:

• якщо немає інформації, записати "не додається";

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

• будь-який матеріал, що не увійшов до секції, повинен бути доданий в "Додаток".

Часто до документа додаються:

• вимоги апаратного і програмного забезпечення;

• модель системи (архітектура);

• словник (термінологія, синоніми, абревіатури);

• зміст.

Найбільш важливі чинники формулювання якісних вимог:

• Стиль :

• ясність - однозначне формулювання, зрозуміле для користувача і розробника;

• структура документа;

• відповідність - ніяких конфліктів у формуванні вимог;

• змінність - формулювання по ключових моментах.

• Гнучкість :

• легке додавання нових вимог.

• Специфікація ролей :

• можливість пов'язати особу з вимогою, описувати дію вимоги.

• Помірність :

• паперовий або електронний варіант;

• контроль версії документа.

Етап аналізу

Аналітична модель системи - модель, яка будується на етапі аналізу.

Аналітичну модель слід представляти у формі єдиного повного документа.

Приклад такого документа:

. Таблиця 2.Форма представлення аналітичної моделі..

План Тіло документу Стандарт: ANSI/IEEE std 830-1993 Рекомендований порядок специфікації вимог програмного забезпечення

Резюме (не більше 200 слів) Зміст Статус документу: автори, компанії, дати і т.д. Зміни, зроблені після останньої версії

1.  Вступ 1.1 Ціль 1.2 Контекст 1.3 Визначення, скорочення, абревіатури 1.4 Посилання 1.5 Короткий огляд 2.  Загальний опис 2.1 Спільне з існуючими проектами 2.2 Спільне з минулими і майбутніми проектами 2.3 Функції та цілі 2.4 Параметри середовища 2.5 Відношення до зовнішніх програм 2.6 Загальні обмеження 2.7 Опис моделі 3.  Вимоги: цей розділ може містити багато функцій, котрі вимагаються від     функціональної декомпозиції 3.1 Функціональні вимоги 3.2 Вимоги продуктивності 3.3 Вимоги відношень з зовнішніми програмами 3.4 Вимоги по ресурсам 3.5 Вимоги перевірки 3.6 Вимоги тестування 3.7 Вимоги до документації 3.8 Вимоги до безпечності 3.9 Вимоги переносимості 3.10 Вимоги якості 3.11 Вимоги надійності 3.12 Вимоги підтримки 2.13 Вимоги захисту 4. Доповнення

Первинні ефекти аналізу:

Покращуються:

• документ з вимогами;

• словник даних;

Створюються:

• документи, що описують створену модель:

  • діаграми класів

  • діаграма випадків використання

  • діаграма дій

  • діаграми станів

  • звіт, що описує визначення класів, ознак, відносин, методів і т.д.;

• графік етапу проектування;

Етап проектування

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

Серед основних результатів етапу проектування є:

• виправлений документ формулювання вимог,

Наступні групи вимоги повинні бути враховані:

1. Вимоги до робочих характеристик.

2. Вимоги до інтерфейсу (протоколи, формати файлів).

3. Експлуатаційні вимоги.

4. Вимоги до ресурсів (число процесорів, об'єм вінчестера).

5. Контрольні вимоги.

6. Тестові вимоги.

7. Вимоги документування.

8. Вимоги безпеки.

9. Вимоги портативності.

10. Вимоги якості.

    1. підбір методу проектування

    2. можливість повторного використання

    3. підбір інструментів

    4. можливість зовнішнього доступу

11. Вимоги надійності.

12. Інструкція по технічному обслуговуванню.

13. Можливість усунення відмов або несправностей.

• виправлена модель,

• детальна специфікація

• документ, що описує проект:

  • діаграми класів,

  • діаграми взаємодій,

  • діаграми станів,

  • діаграми діяльності,

  • діаграми компонентів,

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

Детальний документ проекту

Модель проекту повинна бути записана в документі під назвою «Детальний Документ Проекту» (ДДП).

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

Організація інформації

1. Короткий звіт

2. Зміст

3. Статус документа

4. Опис змін порівняно з минулою версією

ЧАСТИНА I - ЗАГАЛЬНИЙ ОПИС

ВВЕДЕННЯ

Описується мета , визначаються терміни і таблиці посилань.

• Мета - описується мета ДДП і визначається передбачуваний читач.

• Можливості - визначається програмований продукт; описується, що створюється шляхом програмування (і що не створюється); визначаються переваги, цілі і ступені відповідальності.

• Визначення, акроніми, абревіатури.

• Посилання.

Основні положення.