Документація програмного забезпечення: що слід пам’ятати клієнтам і підрядникам

• Важливість документації у розробці програмного забезпечення
• Що таке технічна документація для програмного забезпечення?
• Документація процесу vs документації продукту
• Типи документації програмного забезпечення та їх ключові характеристики
• Зразки та шаблони для документації програмного забезпечення
• Як створити документацію для програмного проєкту: базові рекомендації
• Висновок
• FAQ

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

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

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

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

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

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

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

Що таке технічна документація для програмного забезпечення?

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

Документацію програмного забезпечення можна згрупувати за такими компонентами:

• Документація вимог до програмного забезпечення. Вона описує призначення, можливості та функціональність системи. З цих документів має бути зрозумілою бізнес-логіка системи та ключові особливості продукту. Такі документи також містять користувацькі історії (user stories), критерії прийняття (acceptance criteria) та принципи взаємодії з користувачами.
• Технічна документація є основним джерелом інформації про будь-яке програмне забезпечення, включаючи його код, API, алгоритми тощо. Ці документи описують усі аспекти того, як програмне забезпечення було спроєктовано та як воно працює.
• Документація для кінцевих користувачів. Це інструкції, посібники, довідкові матеріали та інша інформація, призначена для тих, хто користується програмним забезпеченням.
  

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

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

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

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

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

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

Як зазначено вище, технічна документація для розробки програмного забезпечення фактично об’єднує багато документів, які різняться за змістом, призначенням і форматом. Основними типами є:

• Документація з проєктування архітектури програмного забезпечення. Це документи, які фіксують принципи побудови системи, визначають її компоненти та їхнє призначення, а також деталізують будь-які ключові рішення. Окрім цього, така документація описує взаємозв’язки програмного забезпечення з зовнішнім середовищем і потоки даних усередині системи. Важливо, щоб у таких документах були зазначені основні архітектурні рішення, їхні технічні характеристики, а також сформульовані принципи проєктування. Окрім схем і таблиць, бажано, щоб документи містили текстову частину з поясненням, чому були обрані ті чи інші архітектурні рішення та яку роль відіграють окремі елементи архітектури.
• Документація дизайну інтерфейсу користувача (UI) та користувацького досвіду (UX). Документація UX охоплює всі ключові етапи та елементи UX, включаючи посібник зі стилю UX; портрети користувачів та сценарії; карти сценаріїв та історій користувачів; карти сайту; вайрфрейми; макети та прототипи. Документація інтерфейсу користувача стосується взаємодії кінцевого користувача з програмним забезпеченням, і ці документи описують усі можливі дії користувача, включаючи всі візуальні, аудіо та інші елементи взаємодії. Прикладами таких документів є керівництва зі стилю UI; описи компонентів; прототипи; таблиці доступу користувачів тощо.
• Документація API (Application Programming Interfaces), що використовуються в розробці, та інструкції щодо їх ефективного використання та підключення. У цьому контексті доцільно звернути увагу на такі інструменти, як Swagger, який автоматично генерує та оновлює документацію API, підтримуючи її в актуальному стані. Команда проєкту повинна створити список усіх API, які можуть бути використані в подальшій розробці, зі специфікаціями для кожного з них. Крім API, бажано створювати документи щодо інших елементів SDK (software development kit) – набору інструментів розробника.
• Документація вихідного коду та технологічного стеку. Недостатньо просто надати сам код — також необхідно пояснити, як він був створений і як працює. Зверніть увагу на такі моменти: якщо команда проєкту прийняла гайд зі стилю написання коду, його слід включити до пакету документації; документація повинна повністю описувати всі фреймворки, використані для бекенду й фронтенду, із зазначенням особливостей їх застосування; якщо в розробленому програмному забезпеченні важливу роль відіграють системи керування контентом (CMS) та фреймворки керування контентом (CMF), їх необхідно описати й зазначити умови їх використання; усі застосовані шаблони проєктування, плагіни, інструменти або інші рішення, які не були розроблені самостійно, а отримані з зовнішніх бібліотек, також потребують опису; і, нарешті, необхідно задокументувати всі правила безпеки, встановлені в межах проєкту. Загалом, ця частина документації є критично важливою для успішного подальшого функціонування програмного продукту. Тому слід переконатися, що жоден суттєвий аспект не упущено. Усі принципи, внутрішні залежності та взаємозв’язки створеної системи мають бути задокументовані.
• Документація з інсталяції та розгортання. Такі документи необхідні для будь-якого програмного забезпечення, яке вже використовується. Часто повноцінна робота програм неможлива без інтеграції з іншими системами або базами даних, і основні деталі та особливості будь-якої такої інтеграції слід задокументувати.
• Документація із забезпечення якості. Цей розділ документації охоплює всі аспекти тестування та підтверджує якість будь-якого створеного програмного забезпечення. У цій документації міститься важливий перелік стандартів і вимог, яким має відповідати продукт. До змісту такої документації зазвичай входять посібник із управління якістю, план тестування та звітність щодо виконаних тестів і їхніх підсумків. Врахуйте, що документація з тестування програмного забезпечення є значно ширшою темою, яка буде розглянута поза межами цієї статті в інших дослідженнях.
• Інструкції та посібники з обслуговування. Ця інформація призначена насамперед для тих, хто буде займатися підтримкою програмного забезпечення та обслуговуванням його користувачів. Документація повинна містити перелік найтиповіших проблем, що виникають під час роботи системи, та способи їх вирішення. Тут також варто описати всі взаємозв’язки та залежності — як усередині системи, між її окремими частинами, так і між системою та зовнішнім середовищем. Крім того, варто пам’ятати, що документацію можна адаптувати під окремі категорії технічних спеціалістів, які взаємодіятимуть із програмним забезпеченням по-різному. Наприклад, для DevOps-інженерів доцільно створити окремий довідник із відповідями на часті запитання, підготувати інструкції зі встановлення, розгортання та оновлення системи, а також надати опис її функціоналу.

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

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

Зразки та шаблони для документації програмного забезпечення

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

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

• Комплексні платформи для створення та зберігання документації – Atlassian Confluence, Document360, bit.ai, GitHub тощо.
• Ресурси для автоматизованої документації API – Swagger, RAML 2 HTML тощо.
• Системи керування контентом для технічної документації програмного забезпечення – MadCap Flare, Adobe RoboHelp, ClickHelp та інші.
• Шаблони для проєктування програмного забезпечення – Sample Templates, FI, TC Works, cs.iit.edu тощо.
• Зразки архітектури для хмарних рішень – де ви можете отримати багато корисної інформації від усіх провідних постачальників, зокрема Amazon (AWS), Microsoft (Azure), Google (Google Cloud) тощо.

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

Типовим прикладом цього є Business Process Model and Notation (BPMN), за допомогою якого робочі процеси проєкту отримують графічне зображення. У BPMN елементи розташовуються в діаграмах та схемах, що дозволяє відобразити технічні деталі розробки. Подібним чином, Unified Modeling Language (UML) візуалізує дизайн системи за допомогою наборів діаграм, що забезпечує чітке розуміння створеного продукту через комбіноване використання тексту та графіки.

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

Як створити документацію для програмного проєкту: базові рекомендації

Є кілька практичних рекомендацій, які варто врахувати під час підготовки документації. Ми рекомендуємо:

• Майте збалансований список документів. Хоча ваша документація повинна бути повною та всебічною, кількість не завжди означає якість. Варто уникати дублювання однієї й тієї ж інформації в різних місцях, а каталог документів має бути продуманим, структурованим і зручним для використання.
• Створюйте документацію так, як би ви хотіли її отримати. Пам’ятайте про тих, хто читатиме вашу документацію, уникаючи складної мови та двозначності. Не бійтеся вдосконалювати документ, доки він не стане зрозумілим, і ефективно використовуйте візуальні елементи. Прагніть досягти єдиного стилю серед усіх членів команди, які пишуть документацію.
• Враховуйте цільову аудиторію документації. Чітко розумійте, для кого призначений той чи інший документ, і відповідно адаптуйте складність викладу — насиченість термінами чи рівень деталізації — залежно від передбачуваного технічного рівня читача. Допоможіть користувачам орієнтуватися в документації: створюйте глосарій термінів і скорочень, використовуйте перехресні посилання між документами. Оновлюйте документацію синхронно з оновленням програмного забезпечення — у цьому вам стануть у пригоді інструменти контролю версій.
• Регулярно переглядайте документацію. Враховуйте будь-які обговорення, що відбуваються на цьому етапі, та вживайте заходів щодо отриманих відповідних відгуків.
• Заохочуйте членів вашої команди опановувати та розвивати навички підготовки програмної документації в галузі програмної інженерії.
• Організуйте правильне зберігання технічної документації до програмного забезпечення. Ми радимо вам зробити Atlassian Confluence основним місцем для зберігання документів. Резервні копії можна розміщувати разом із кодом у репозиторіях програмного забезпечення.
• Слідкуйте за найкращими практиками та інструментами для створення документації в галузі програмної інженерії — не бійтеся тестувати їх і робити власні висновки щодо доцільності подальшого використання. Час від часу на ринку з’являється справді вартісне програмне забезпечення для документування процесів. Наприклад, для опису API доцільно використовувати Swagger — цей фреймворк автоматизує створення документації до API, який є ключовим елементом будь-якого проєкту розробки.
• Пам’ятайте: детальна й якісна документація — це ознака зрілої команди розробників. Звертайте увагу на питання технічної документації під час переговорів із потенційними підрядниками та враховуйте цей фактор під час вибору компанії для реалізації вашого проєкту.
• Зробіть документацію одним із ваших пріоритетів при замовленні програмного забезпечення. Розробники можуть не приділяти достатньо уваги програмній документації або можуть бути недостатньо заохочені надавати повний комплект документації замовникам. Особливо це стосується випадків, коли проєкт має бути переданий іншій команді або співробітникам клієнта. Саме замовник найбільше страждає від нестачі достатньої кількості документів, тому саме замовник повинен забезпечити створення та постійне оновлення документації, а також її збереження. Переконайтеся, що всі учасники проєкту знають, що документація не є другорядним завданням.

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

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

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

Висновок

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

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

FAQ: