Документація для програмного забезпечення - це довідковий текст і візуальна інформація, що описують і відображають процес розробки, виробництва, експлуатації та супроводу програмного продукту, його споживчі властивості і технічні характеристики.
Види документації для програмного забезпечення
Відповідно до таким визначенням, технічна документація по ПЗ складається з чотирьох основних типів:
• Проектна - включає опис основних положень, які використовуються при створенні ПЗ та робочого середовища.
• Технічна - алгоритми, код, інтерфейси, АРI.
• Призначена для користувача - керівництва для користувачів програми.
Проектна документація, як правило, програмний продукт описує в загальних рисах. Наприклад, програміст в проекті може обгрунтувати, чому структури даних саме таким (а не іншим) чином організовані. Чому саме таким чином сконструйований той чи інший клас. У проекті виділяються патерни. Часто даються вказівки, як виконувати модернізацію програми.
Технічна документація (всі зазначені види якої можна замовити в компанії "ТехРайтКонсалт"). не тільки вказує конкретні коди. Вона, як правило, також описує різні аспекти того, що цей код робить. Вона має явно виражений технічний характер і використовується в основному для опису і визначення API, алгоритмів і структур даних. При її складанні можливе використання генераторів документації (Doxygen, NDoc, javadoc і ін.), Що дає можливість постійно підтримувати таку документацію в актуальному стані. В останньому випадку технічна документація є частиною вихідного коду. Тоді одні і ті ж інструменти можна використовувати як для збірки програми, так і для збірки в той же час документації до неї.
Хороша для користувача документація складається з:
• вступного керівництва, де розглядаються загальні питання виконання типових завдань;
• тематичного, де кожна глава присвячена роз'ясненню будь-якого розділу експлуатації програми;
• алфавітного довідника, для досвідчених користувачів, які добре знають, що потрібно шукати.
Стандарти для розробки ПО
Основою для створення будь-якої документації на програмні продукти служать стандарти.
В таких умовах IT-компанії питання розробки документації для програмного забезпечення вирішують по-різному. Одні намагаються копіювати і впроваджувати західні стандарти. Інші - використовувати вітчизняні. Треті - створюють свої власні.
Актуальні питання при розробці документації ПО
У будь-якому випадку актуальними при розробці технічної документації для програмного забезпечення будуть такі основні питання:
• Яка нормативна база і як її слід застосовувати?
• Яка саме документація потрібна серед величезної кількості документів?
Зупинимося на цих питаннях докладніше.
В даний час діють такі нормативні документи документування:
ГОСТ 19.201 (Єдина система програмної документації (ЕСПД);
ГОСТ 34.602 (Комплекс стандартів на автоматизовані системи (КСАС).
Слід також пам'ятати, що відповідно до ФЗ «Про технічне регулювання» національні стандарти мають завжди пріоритет над міжнародними. Тобто, використовувати міжнародні стандарти можна лише у випадках, якщо останні не суперечать національним! Благо, свободи дій вітчизняні стандарти надають набагато більше зарубіжних. Останні переглядаються кожні 5-7 років і характеризуються більшою конкретизацією, але відображають весь життєвий досвід за вказаний період часу. Вітчизняні ж (не маючи настільки розробленої конкретики) характеризуються глибокою розробкою концептуальних моментів. Це дозволяє створювати на їх основі непогані стандарти відповідно до вимог часу.
Основним документом на створення програмного продукту є технічні завдання, яке використовується для розробки (проектування) програми і її випробування.
У ТЗ встановлюється призначення програмного продукту, що розробляється, його технічні характеристики, якість і техніко-економічні показники, а також вказівки щодо виконання стадій документації (конструкторської, програмної, технологічної тощо), її склад та інші спеціальні вимоги.
Технічне завдання - це юридичний документ, який в якості додатку включається в договір на виконання проектних робіт по створенню програми і є основою такого договору.
ТЗ може бути виконано як в якості ескізного проекту (описуються структура системи та її функції без технологій реалізації рішення); так і в формі технічного проекту (детальний опис обраної технології реалізації проекту). ТЗ може складатися також в загальних рисах (для інвесторів, наприклад) і з самої докладною деталізацією (для програмістів і в інших випадках).
Часто ТЗ є єдиним документом для опису розроблюваного програмного продукту. У таких випадках особливо важливо, щоб воно розроблялося і виготовлялося професіоналами.