Технічна документація в розробці ПЗ: типи, найкращі практики

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

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

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

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

Продукт: Документація користувача

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

1. Документація для кінцевих користувачів (End-user documentation). 

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

Основні типи документації користувачів.

• Короткий посібник із початку роботи (quick start guide): містить огляд функціональних можливостей продукту та дає основні вказівки щодо його використання.
• Повний посібник (complete manual): містить вичерпну інформацію та інструкції щодо встановлення та використання продукта. У ньому наведено вимоги до обладнання та програмного забезпечення, детальний опис функцій, вказівки щодо того, як отримати від них максимальну користь, поради та підказки тощо.
• Посібник з усунення несправностей (troubleshooting guide): надає кінцевим користувачам інформацію про те, як знайти та вирішити можливі проблеми, які можуть виникнути під час використання продукту.

Іноді в компаніях для об’ємних продуктів деякі частини документації користувача, як-от навчальні посібники, замінюють навчальними курсами. 

Інтернет-документація кінцевого користувача може надходити у формі баз знань і містити такі розділи:

• поширені запитання;
• відеоуроки;
• вбудована допомога;
• портали підтримки.

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

2. Документація для системного адміністратора (System administrators' documentation).

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

Стандартні документи для системних адміністраторів наступні:

• функціональний опис (functional description): описує функціональні можливості продукту, більша частина цього документа створена після консультації з користувачем або власником;
• посібник системного адміністратора (system admin guide): пояснює різні типи поведінки системи в різних середовищах і з іншими системами, надає інструкції щодо того, як діяти у випадках несправності.

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

Документація процесу

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

Розглянемо поширені типи документації процесу.

Плани, кошториси та графіки (Plans, estimates, and schedules)

Ці документи зазвичай створюються до початку проєкту та можуть бути змінені по мірі розвитку продукту.

Звіти і метрики (Reports and metrics)

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

Робочі документи (Working papers)

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

Стандарти (Standards)

Цей документ повинен містити всі стандарти кодування та UX, яких дотримується команда під час роботи з проєктом.

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

Основна мета документування процесів – скоротити обсяг системної документації.

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

Розглянемо практики, які можуть допомогти оптимізувати та прискорити процес написання документації та подальшого керування нею.

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

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

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

Використовувати скріншоти та візуальні матеріали. Завжди варто використовувати знімки екрана та інші зображення, оскільки вони допоможуть швидко знайти те, що потрібно оновити.

Зберігати документацію з вихідним кодом. Краще зберігати технічну документацію разом із вихідним кодом, але тримати їх окремо. Це допоможе підтримувати код в актуальному стані та дозволить усім знати, де його знайти.

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

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

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

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

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