Що саме містить "Документація"?

Коли ми говоримо "документація" на програмний продукт, що це включає і що не повинно включати?

Наприклад, нещодавнє запитання, чи вважають коментарі документацією?

Але є багато інших областей, до яких також належить питання, яке є більш очевидним, ніж інші:

• Посібники (очевидно)
• Нотатки до випуску?
• Підручники
• Коментарі
• Будь-які інші?

Де намальована лінія Наприклад, якщо "підручник" - це документація, це "відео-підручник", чи це щось інше?

Як правило, щось у програмному забезпеченні не робиться, поки воно не буде реалізовано, протестовано та задокументовано. Звідси це питання, які речі ми повинні розглядати як частину документації, щоб вважати щось "зроблене".

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

_{Аудиторія: Розробники програмного забезпечення, що використовують наші бази даних, мови програмування та пов'язані з ними інструменти (наприклад, клієнти адміністратора до вказаного БД)}

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

Зважаючи на мету (пояснення програмного забезпечення), документація закінчується, коли клієнт задоволений поясненням : так само, як програмне забезпечення закінчено, коли клієнт задоволений програмним забезпеченням. Майте на увазі, що замовник документації не завжди такий, як клієнт, який платить за програмне забезпечення: персонал підтримки, тестери, продавці та інші потребуватимуть певного розуміння того, що робить програмне забезпечення та як воно працює.

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

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

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

Що стосується документації ... ну, це майже все, що ви перерахували, і, можливо, ще кілька речей, яких ви не зробили. Але ніхто не може сказати, скільки документації потрібен ваш проект. Кожен проект різний, і визначати рівень та тип документації, необхідний для вашого проекту, залежить від вашої команди, власника товару та ваших клієнтів.

Деякі фактори, які можуть зіграти:

• Ви розробляєте програмне забезпечення v1.0, і вони переходять до інших проектів чи це поточний довгостроковий проект? Коментарі / дизайнерські документи стають набагато важливішими в останньому випадку. З іншого боку, якщо ваш клієнт - це магазин пончиків для мам і попсів, і ви пишете для них веб-сайт, який ви ніколи не побачите ... ну, мабуть, документація з кодом приємна, але це не так важливо.
• Ви розробляєте мобільну гру чи програмне забезпечення, яке контролює монітор серцевого ритму в лікарні. Здогадайтесь, яке з них матиме визначення "зроблено", яке має набагато більше документації?
• Ваші клієнти типові кінцеві споживачі чи вони інші розробники? Чи є у вас API / SDK, який ви виставляєте?
• Який рівень знань ваших клієнтів? Це впливає на вибір відеоуроку проти письмового матеріалу порівняно з якоюсь інтерактивною програмою підручника
• Ваші клієнти дбають про те, що змінилося від версії до версії. Деякі так і роблять. Більшість ні. Для мало кого слід піклуватися про закон (або близький до цього).

Документація - це матеріал, призначений для читання, не змінюючи його.

Я думаю, ви не можете помилитися з визначенням на основі цілей ... але тільки якщо правильно визначити мету.

• ^{Правильно визначити мету документації не зовсім просто. Відверта (наївна, якщо хочете) різниця, яка, природно, спадає на думку, що документація - це все, що призначено для читання - тоді як, для порівняння, код - це все, що призначене для виконання комп'ютера . На поверхні звучить добре, чи не так? але це справді виявляється досить потворно, коли ви копаєтеся глибше.
   
  Справа в тому, що хороший код враховує питання читабельності, а також правильність виконання - це робить розбір "читабельності" досить марним у визначенні документації.
   
  Самі зразки, про які ви згадали, показують, що з цим не так. Зазвичай клієнти очікують, що вони будуть чітко написані тавиконати правильно. Порушення читання чи коректності може спричинити водоспад скарг клієнтів. Наївне розрізнення не допомагає зрозуміти, чи є зразки кодом чи документацією.
   
  Використання наївного розрізнення стане ще більш безладним, якщо ви уявляєте, що працюєте з відкритим кодом . Ви завантажуєте, створюєте та запускаєте - ви не читаєте, це просто код, правильно? Зачекайте, щось якимось чином пішло не так, і ви переходите до коду, щоб прочитати, що там відбувається ... Ей, ви читаєте, не виконуєте - це зараз документація? І, нарешті, ви виявляєте помилку у вихідному коді та виправляєте її - тепер це справді код, це не щось, як правило, називається документація, незалежно від того, наскільки ретельно ви його читали, щоб зробити це виправлення.}

Для "зразків", які ви збираєтеся надати, відмінність читання, що не змінюється, може виявитися досить важливою.

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

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

Все, що відповідає на питання "як я ..." - це документація.

Для розробників це означає специфікації вимог ("як я знаю, що писати"), конструкторські документи ("як я вирішую свої вимоги"), матриці відстеження ("як я знаю, що мій дизайн розрахований на всі мої вимоги"), плани випробувань ( «як я знаю , що мій код працює»), модульні тести ( «як я знаю , що я маю safisfied вимоги X»), вбудовані коментарі ( "як я можу переконатися , що наступний бідний schlub розуміє , чому я це написав це спосіб "), інструкції з розгортання (" як я упакую цей продукт для встановлення ") тощо

Для користувачів це означає посібники користувача ("як я використовую програмне забезпечення"), навчальні посібники ("як я використовую цю специфічну функцію"), примітки до випуску ("як я знаю, які помилки були виправлені / нові функції помилок були додано ") тощо.