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

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

Різні типи документів створюються протягом усього життєвого циклу розробки програмного забезпечення (SDLC). Документація існує для того, щоб пояснити функціональність продукту, уніфікувати інформацію, пов’язану з проєктом, і дозволити обговорити всі важливі питання, що виникають між зацікавленими сторонами та розробниками. Крім того, помилки в документації можуть створити прогалини між баченням зацікавлених сторін та QA спеціалістів і, як наслідок, запропоноване рішення не буде відповідати очікуванням. Отже, велика увага має приділятися якості документації.

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

Всю технічну документацію можна розділити на дві головні категорії:

• документація продукту;
• документація процесу.

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

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

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

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

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

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

Документ вимог до продукту (Product requirement document)

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

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

Які пункти слід включити в документ з вимогами до продукту?

1. Ролі та обов’язки. Вказується інформація про учасників проєкту, включаючи власника продукту, членів команди та зацікавлені сторони.
2. Цілі команди та бізнес-цілі. Коротко описуються найважливіші цілі.
3. Передумови та стратегічна відповідність. Стисло описується  пояснення стратегічної мети своїх дій. (Чому створюється продукт? Як впливають певні дії на розвиток продукту? Чи відповідають результати цих дій цілям компанії? і т.п.)
4. Припущення. Список технічних або бізнес-припущень, які може мати команда.
5. Історії користувачів (User Stories). Перелічуються історії користувачів, які потрібні для проєкту.
6. Приймальний критерій (Acceptance criteria). Визначається задовільний результат для сценарію використання з точки зору кінцевого користувача.
7. Взаємодія з користувачем і дизайн. Дослідження дизайну та карти екранів (wireframes).
8. Питання. Хорошою практикою є записувати всі питання, які виникають під час просування проєкту.
9. Не робити. Перелічуються речі, які зараз не будуть виконуватися, але які планується зробити найближчим часом. Такий список допоможе організувати командну роботу та визначити пріоритети функцій.

Всю цю інформацію можливо зробити більш вичерпною, використовуючи такі методи:

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

Документація дизайну взаємодії з користувачем (User experience design documentation)

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

Етап дослідження включає:

• • користувацькі персони (user personas): представляють ключові характеристики реальних користувачів, зосереджуючись на поведінці, моделях мислення та мотивації;
  • користувацький сценарій (user scenario): описує кроки, які користувач зробить для виконання певного завдання (увага зосереджується на тому, що користувач буде робити, а не на описі процесу мислення);
  • карти сценарію (scenario maps): показують усі можливі сценарії, доступні в певний момент для кожної окремої функції, а також пересічні етапи сценарію;
  • карта історії користувача (user story map): формується з беклога продукта і допомагає впорядкувати історії користувача в майбутні функції або частини програми;
  • керівництво по UX стилю (UX style guide): містить шаблони дизайну майбутнього продукту, а також описує всі можливі елементи інтерфейсу користувача, що використовуються та типи вмісту, визначаючи правила їх розташування та взаємодії один з одним.

На етапі створення прототипів та проєктування створюються такі документи:

• • карти сайту/продукту (site/product maps): представляють собою схеми, на яких відображено зв’язок між усіма сторінками продукту і допомагають команді візуалізувати структуру веб-сайту чи програми та зв’язки між сторінками/функціями;
  • каркаси (wireframes): схеми, які показують, як розташувати елементи на сторінці та як вони повинні поводитися (але не показують, як ці елементи мають виглядати);
  • макети (mock-ups): демонструють фактичний вигляд продукту і мають вигляд статичних зображень, що представляють кінцевий дизайн;
  • прототипи (prototypes): по суті це макети, з якими можна взаємодіяти (натискати кнопки, переходити між різними сторінками, тощо);
  • схеми потоку користувачів/шляхів користувачів (user flow schemes/user journey): допомагають команді визначити кроки, які користувач повинен пройти через увесь продукт, основним завданням цих схем є зображення можливих кроків, які користувач може зробити, переходячи від сторінки до сторінки;
• звіти про тестування зручності використання (usability testing reports): короткі документи зі зворотним зв’язком, створені для передачі результатів тестування зручності використання.

Проєктний документ архітектури ПЗ (Software architecture design document)

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

Документ із вихідним кодом (Source code document)

Це документ, у якому пояснюється, як працює код. Основними користувачами документів вихідного коду є інженери-програмісти.

Документи з вихідним кодом можуть включати, але не обмежуватися, наступними деталями:

• фреймворк генерації HTML та інші застосовані фреймворки;
• тип прив'язки даних;
• шаблон проєктування з прикладами;
• заходи безпеки.

Документація із забезпечення якості (Quality assurance documentation)

До цього типу документації відносяться наступні найпоширеніші види.

• • План управління якістю (quality management plan): є налогом документа-вимоги, присвяченого тестуванню, встановлює необхідні стандарти якості продукції та описує методи досягнення цього рівня. План допомагає планувати завдання з контролю якості та керувати діяльністю тестування для менеджерів із продуктів, але в основному він використовується для великомасштабних проєктів.
  • Стратегія тестування (test strategy): описує підхід до тестування ПЗ для досягнення цілей тестування, містить інформацію про структуру команди та потреби в ресурсах, а також про те, що має бути пріоритетним під час тестування. Стратегія тестування зазвичай є статичною, оскільки стратегія визначається для всієї області розробки.
  • Тест-план (test plan): описує, що потрібно перевірити в даний момент. Цей документ має містити: перелік функцій для тестування, методи тестування, часові обмеження, ролі та обов’язки.
  • Специфікації тест-кейсів (test case specifications): набір детальних дій для перевірки кожної окремої функції/функціоналу продукта. Зазвичай команда QA пише окремі специфікації тест-кейсів для кожної одиниці продукту. Специфікація тест-кейсів базуються на підході, викладеному в тест-плані.
  • Тестові чеклісти (test checklists): це список тестів, які слід виконати в певний час, він показує, які тести пройдено та скільки невдалих.

Керівництво з технічного обслуговування та допомоги (Maintenance and help guide)

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

Документація API (API documentation)

Майже будь-який продукт має свої API (Application Programming Interfaces). Документація API інформує розробників про те, як ефективно використовувати та підключатися до необхідних API. Цей тип документації також має містити список усіх доступних API зі специфікаціями для кожного з них.

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