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

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

Метод1 З 2:

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

Визначте, яка інформація повинна бути згадана.документи про вимоги до програмного забезпечення служать довідковим посібником для дизайнерів інтерфейсу користувача, програмістів, які пишуть код і тестерів, які перевіряють, чи працює програмне забезпечення як слід. Точна інформація залежить від самої програми, однак може включати наступне:
- Файли ключів в додатку. Це можуть бути файли, створені командою розробників, бази даних, що викликаються під час програмної операції, і службові програми третьої сторони.
- Функції та підпрограми. Тут вказується, що робить кожна функція і підпрограма, включаючи вхідні і вихідні значення.
- Програмні змінні і постійні і як вони використовуються в додатку.
- Загальна структура програми. Для додатків на основі диска вам, ймовірно, знадобиться опис окремих блоків і бібліотек програми, в той час, як для веб-додатків знадобляться опис сторінок, які використовую файли.
Вирішіть, скільки документації має бути в програмному коді і як багато має бути відокремлено. чим більше технічної документації створено в програмному коді, тим простіше буде оновлювати цей код, як і документацію, що стосується різних версій оригінального додатка. Як мінімум документація в програмному коді повинна пояснювати функції, підпрограми, програмні постійні і змінні.
- Якщо програмний код досить довгий, його можна оформите у вигляді довідкового файлу, в якому можна робити пошук за ключовими словами або покажчиками. Це буде великим плюсом для додатків, де логіка програми розділена на багато сторінок і включає номери допоміжних файлів, як і в певних веб-додатках.
- Деякі мови програмування, наприклад Java або NET Framework (Visual Basic.NET, c#), мають свої власні стандарти для коду документації. У таких випадках дотримуйтесь стандартних вказівок-скільки документації слід включати в програмний код.
Виберіть відповідний інструмент. в якійсь мірі це визначається мовою, на якому код написаний, будь Це C++, C#, Visual Basic, Java, або PHP - для кожного існують свій власний інструмент. В інших випадках використовуваний інструмент визначається типом необхідної документації.
- Текстовий редактор "Microsoft Word" - відповідний інструмент для створення окремих текстових файлів документації, яка буде простою і короткою. Для довгих текстових файлів багато розробників технічної документації воліють вибирати програму "Adobe FrameMaker".
- Файли підказки для документації програмного коду можуть писатися за допомогою будь-якого інструменту, наприклад "RoboHelp», «Help and Manual», «Doc-To-Help», «MadCap Flare», або "HelpLogix".

Метод2 З 2:

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

Визначте комерційні міркування для Вашої документації.хоча функціональні причини для програмної документації-допомогти користувачам зрозуміти, як використовувати додаток, є й інші причини, наприклад, допомогти в просуванні товару на ринку, поліпшення образу компанії і найголовніше, зменшення витрат на технічну підтримку. У певних випадках документація потрібна для дотримання певних правил і юридичних вимог.
- Ні в якому разі програмна документація не повинна замінювати поганий дизайн інтерфейсу. Якщо екран програми вимагає багато пояснювальної документації, то краще змінити дизайн на щось більш інтуїтивне.
Зрозумійте аудиторію, для якої Ви пишете документацію.у більшості випадків користувачі програмного забезпечення мало знають про комп'ютери крім завдань програми. Є кілька способів визначити, як узгодити їхні потреби з документацією.
- Подивіться на професії, якими володіють ваші потенційні користувачі. Системний адміністратор, швидше за все, буде експертом у використанні Програм програмного забезпечення, в той час як оператор введення даних, швидше за все, володіє додатком, яке він або вона в даний момент використовує для введення даних.
- Подивіться і на самих користувачів. Хоча їх посади в цілому визначають те, чим люди займаються, але бувають значні відмінності в тому, як певні посади використовуються в даній організації. Провівши співбесіду з потенційними користувачами, Ви можете скласти свою думку - чи відповідає назва посади виконуваним обов'язкам.
- Перегляньте існуючу документацію. Документація для попередніх версій програмного забезпечення дає приблизне поняття, що користувачеві потрібно знати про використання програми. Однак пам'ятайте, що кінцеві користувачі не зацікавлені в тому, як працює програма, їм важливо знати, що вони можуть з нею робити.
- Визначте завдання, які необхідні для цієї роботи і які завдання повинні бути виконані до того, як ці завдання можуть бути виконані.
Визначте відповідний формат (и) документації. програмна документація може бути структурована в одному з двох форматів-довідкове керівництво та інструкція з користування. Іноді краще вибрати змішаний варіант з цих двох форматів.
- Довідкове керівництво покликане пояснювати інструментарій програмного обладнання (кнопки, таблиці, поле і панель діалогу) і як цей інструментарій працює. Багато файлів підказки написані в цьому форматі, а контекстні підказки допомагають показати потрібну тему після того як користувач клацає на кнопку» допомога " на потрібному екрані.
- Інструкція з користування пояснює, як використовувати програмне забезпечення для виконання певного завдання. Інструкція з користування часто має вигляд друкованого керівництва або формат PDF, хоча деякі файли підказки включають теми про те, як виконувати певне завдання. (Ці теми довідки зазвичай не є контекстними, хоча можуть бути гіперпосиланнями) інструкція з користування часто має форму довідника З опис завдання і покроковою інструкцією.
Вирішіть, який має бути формат (формати) документації. програмна документація для кінцевих користувачів може бути одного або декількох форматів: друковане керівництво, документи у форматі PDF, файли підказки або онлайн-довідка. Кожен з цих форматів створений, щоб показати користувачеві, як використовувати кожну програмну функцію – будь це короткий огляд або керівництво. Як у випадку з файлами підказки та онлайн-довідкою, документація може мати демонстраційне відео або текст з картинками.
- Файли підказки та онлайн-довідка повинні мати покажчики, пошук за ключовими словами, що дозволить користувачеві швидко знайти необхідну інформацію. Хоча інструменти для файлів підказок можуть автоматично створювати покажчики, краще це робити вручну, використовуючи терміни, які користувачі, швидше за все, стануть шукати.
Виберіть відповідний інструмент для створення документації.друковані посібники або формат PDF можуть писатися в текстових редакторах, таких як «Word» або «FrameMaker», в залежності від довжини і складності керівництва. Файли підказок можна писати за допомогою таких засобів розробки як "RoboHelp», «Help and Manual», «Doc-To-Help», «Flare», «HelpLogix», or "HelpServer".

Поради

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