Як писати програмну документацію
Хороша програмна документація - будь це документ, що містить специфікацію вимог для програмістів або тестерів, технічний документ для внутрішніх користувачів, керівництво для використання програмного забезпечення або файл підказок для користувачів - допомагає людині, яка працює з програмним забезпеченням, зрозуміти його характерні риси та функції. Дотримуйтесь порад - як писати програмну документацію для технічних і кінцевих користувачів.
Зміст
кроки
Метод 1 з 2: Написання програмної документації для технічних користувачів.1
Визначте, яка інформація повинна бути згадана. Документи про вимоги до програмного забезпечення слугують довідковою керівництвом для дизайнерів інтерфейсу користувача, програмістів, які пишуть код і тестерів, які перевіряють, чи працює програмне забезпечення як слід. Точна інформація залежить від самої програми, проте може включати наступне:
- Файли ключів в додатку. Це можуть бути файли, створені командою розробників, бази даних, що викликаються під час програмної операції, і службові програми третьої сторони.
- Функції та підпрограми. Тут вказується, що робить кожна функція і підпрограма, включаючи вхідні та вихідні значення.
- Програмні змінні і постійні і як вони використовуються в додатку.
- Загальна структура програми. Для додатків на основі диска вам, ймовірно, знадобиться опис окремих блоків і бібліотек програми, в той час, як для веб-додатків знадобляться опис сторінок, які використовую файли.
2
Вирішіть, як багато документації повинно бути в програмному коді і як багато належить відокремлювати. Чим більше технічної документації створено в програмному коді, тим простіше буде оновлювати цей код, як і документацію, що стосується різних версій оригінального програми. Як мінімум документація в програмному коді повинна пояснювати функції, підпрограми, програмні постійні і змінні.
3
Виберіть відповідний інструмент. В якійсь мірі це визначається мовою, на якому код написаний, будь це C ++, C #, Visual Basic, Java, або PHP - для кожного існують свій власний інструмент. В інших випадках використовується інструмент визначається типом необхідної документації.
1
Відео: 9002 Трохи про ГОСТах
Визначте комерційні міркування для вашої документації. Хоча функціональні причини для програмної документації - допомогти користувачам зрозуміти, як використовувати додаток, є й інші причини, наприклад, допомогти в просуванні товару на ринку, поліпшення образу компанії і найголовніше, зменшення витрат на технічну підтримку. У певних випадках документація потрібна для дотримання певних правил і юридичних вимог.
- Ні в якому разі програмна документація не повинна замінювати поганий дизайн інтерфейсу. Якщо вікні керування вимагає багато пояснювальній документації, то краще змінити дизайн на щось більш інтуїтивне.
Відео: Про курс "Програмування на PERL" | Технострим
2
Розумійте аудиторію, для якої ви пишете документацію. У більшості випадків користувачі програмного забезпечення мало знають про комп`ютери крім завдань програми. Є кілька способів визначити, як узгодити їх потреби з документацією.
3
Відео: 4. Perl. Регулярні вирази і юнікод
Визначте відповідний формат (и) документації. Програмна документація може бути структурована в одному з двох форматів - Довідку і інструкція по користуванню. Іноді краще вибрати змішаний варіант з цих двох форматів.
4
Вирішіть, який повинні бути формат (формати) документації. Програмна документація для кінцевих користувачів може бути одного або декількох форматів: друковане керівництво, документи в форматі PDF, файли підказки або онлайн-довідка. Кожен з цих форматів створений, щоб показати користувачеві, як використовувати кожну програмну функцію - будь це короткий огляд або керівництво. Як у випадку з файлами підказки та онлайн-довідкою, документація може мати демонстраційне відео або текст з картинками.
5
Виберіть підходящий інструмент для створення документації. Друковані керівництва або формат PDF можуть писатися в текстових редакторах, таких як "Word" або "FrameMaker", В залежності від довжини і складності керівництва. Файли підказок можна писати за допомогою таких засобів розробки як "RoboHelp", "Help and Manual", "Doc-To-Help", "Flare", "HelpLogix", or "HelpServer".
Поради
- Текст повинен бути простим для читання, картинки повинні розташовуватися якомога ближче до тексту, до якого вони належать. Розбийте документацію на розділи і логічні теми. Кожен розділ або тема повинна стосуватися певного питання, будь це одна програма або завдання. Суміжні питання повинні бути позначені "дивитися також" з гіперпосиланням, якщо потрібно.
- Всі інструменти для створення документації, які були перераховані вище, можуть доповнюватися програмою по створенню скріншотів, наприклад "Snagit", Якщо в документації потрібна певна кількість скріншотів. Як і з іншою документацією скріншоти повинні пояснювати, як працює програмне забезпечення, а не вводити користувача в оману.
- Також дуже важливий тон написання документації, особливо якщо вона пишеться для кінцевих користувачів. Використовуйте другий особа "ви", Замість третьої особи "користувачі".
Що вам знадобиться
- Інструмент для написання документації / засіб розробки
- Інструмент для створення скріншотів
Поділися в соц мережах: