Як писати документацію до програмного забезпечення

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

Різновидів подібної документації безліч: це і специфікації і методики тестування, і тексти програм, і керівництва і всілякі довідки для користувача. Для зручного використання подібної документації вона повинна бути коротка за обсягом, актуальна за змістом, сповнена за змістом.

Існують два способи написання технічної документації.

Спосіб 1. Написання технічної документації для фахівців.

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

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

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

Спосіб 2. Написання технічної документації для кінцевих користувачів.

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

2. Визначення цільової аудиторії. Досить рідко широке коло користувачів є фахівцями в якійсь конкретній області. Для виділення цільової аудиторії:

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

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

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

3. Виберіть формат подачі даних при написанні технічної документації. Зазвичай це або довідкове керівництво, або керівництво користувача.

4. Виберіть форму для документів (різні довідки, PDF-файли, друковані керівництва і т.д.).

5. Виберіть зручний інструмент документування (програмне забезпечення).