Masha26081

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

Документ — елемент документації: цільова інформація, призначена для конкретної аудиторії, розміщена на конкретному носії (наприклад, в книзі, на диску, в короткій довідковій карті) в визначеному форматі.

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

Типи документації

Існує чотири основних типи документації на ПЗ:

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

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

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

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

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

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

Часто при створенні технічної документації використовуються автоматизовані засоби — генератори документації, такі як Doxygen, javadoc, NDoc і інші. Вони отримують інформацію з спеціальним чином оформлених коментарів у вихідному коді, і створюють довідкові керівництва в якомусь форматі, наприклад, у вигляді тексту або HTML.

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

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

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

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

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

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

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

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

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

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

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

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