Як писати програмну документацію: 8 кроків

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

кроки

Метод 1 з 2:

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

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

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

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

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

Деякі мови програмування, наприклад Java або NET Framework (Visual Basic.NET, C #), мають свої власні стандарти для коду документації. У таких випадках виконуйте стандартні вказівкам - скільки документації слід включати в програмний код.

3. Виберіть підходящий інструмент. В якійсь мірі це визначається мовою, на якому код написаний, будь це C ++, C #, Visual Basic, Java, або PHP - для кожного існують свій власний інструмент. В інших випадках використовується інструмент визначається типом необхідної документації.

Текстовий редактор «Microsoft Word» -подходящій інструмент для створення окремих текстових файлів документації, яка буде простий і короткою. Для довгих текстових файлів багато розробників технічної документації за краще вибирати програму «Adobe FrameMaker».

Файли підказки для документації програмного коду можуть писатися за допомогою будь-якого інструменту, наприклад «RoboHelp», «Help and Manual», «Doc-To-Help», «MadCap Flare», або «HelpLogix».

Метод 2 з 2:

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

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

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

2. Розумійте аудиторію, для якої ви пишете документацію. У більшості випадків користувачі програмного забезпечення мало знають про комп`ютери крім завдань додатки. Є кілька способів визначити, як узгодити їх потреби з документацією.

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

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

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

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

3. Визначте відповідний формат (и) документації. Програмна документація може бути структурована в одному з двох форматів - Довідку і інструкція по користуванню. Іноді краще вибрати змішаний варіант з цих двох форматів.

Довідкове керівництво покликане пояснювати інструментарій програмного обладнання (кнопки, таблиці, поле і панель діалогу) і як цей інструментарій працює. Багато файли підказки написані в цьому форматі, а контекстні підказки допомагають показати потрібну тему після того як користувач клацає на кнопку «допомога» на потрібному екрані.

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

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

Файли підказки та онлайн-довідка повинні мати покажчики, пошук за ключовими словами, що дозволить користувачеві швидко знайти необхідну інформацію. Хоча інструменти для файлів підказок можуть автоматично створювати покажчики, краще це робити вручну, використовуючи терміни, які користувачі, швидше за все, стануть шукати.

5. Виберіть підходящий інструмент для створення документації. Друковані керівництва або формат PDF можуть писатися в текстових редакторах, таких як «Word» або «FrameMaker», в залежності від довжини і складності керівництва. Файли підказок можна писати за допомогою таких засобів розробки як «RoboHelp», «Help and Manual», «Doc-To-Help», «Flare», «HelpLogix», or «HelpServer».

Поради

Текст повинен бути простим для читання, картинки повинні розташовуватися якомога ближче до тексту, до якого вони відносяться. Розбийте документацію на розділи і логічні теми. Кожен розділ або тема повинна стосуватися певного питання, будь це одна програма або завдання. Суміжні питання повинні бути позначені «Дивитися також» з гіперпосиланням, якщо потрібно.
Всі інструменти для створення документації, які були перераховані вище, можуть доповнюватися програмою по створенню скріншотів, наприклад «Snagit», якщо в документації потрібна певна кількість скріншотів. Як і з іншою документацією скріншоти повинні пояснювати, як працює програмне забезпечення, а не вводити користувача в оману.
Також дуже важливий тон написання документації, особливо якщо вона пишеться для кінцевих користувачів. Використовуйте другий особа «ви», замість третьої особи «користувачі».