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

Мене звати Інна Козак, я Founder of Jungle Courses, CEO в Jungle Consulting, менторка курсів QA та PM.

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

Отже, давно відома практика витрачати ресурси на документування. Сучасний аутсорс-ринок пропонує послуги з документування ІТ-проєктів як must-have для успішного бізнесу. Замовив і забув. Але яка справжня користь документування на проєкті? І чи справді спеціаліст зовні зможе дати таку користь?

Ілюстрація Аліни Самолюк

Проблема документування на продуктових проєктах

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

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

Отже, основний недолік — брак інформації. Де її взяти?

Збирати інформацію по частинках в кожного учасника команди.
Піднімати історію тасків/фіч/багів.
Починати описувати роботу проєкту/фіч.
Інше.

Проте не все так просто з кількох причин:

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

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

А що в аутсорсі

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

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

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

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

Вихід: налагоджена комунікація та документування від А до Я.

Що таке документація на проєкті. Яка вона буває

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

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

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

Product documentation
Process documentation

Product documentation описує продукт, який розробляють, та містить інструкції щодо виконання різних завдань з ним. Загалом це вимоги, технічні характеристики, логіка та мануали. Два основних типи product documentation:

System documentation — документи, що описують саму систему та її частини. Це Requirement documents, Design decisions, Architecture descriptions, Program Source code, Testing documents.
User documentation — це інструкції, які підготовлені переважно для кінцевих користувачів продукту та команди підтримки. Це Tutorials, User guides, Troubleshooting manuals, Installation, Reference manuals.

Process documentation описують процес. Можуть бути Standards, Project plans, Test schedules, Reports, Meeting notes тощо.

Чим документи відрізняються від проєкту до проєкту

Усе починається з вимог Product requirement document , однак бувають винятки. Тут можна практикувати, хто як вміє. Головне — описати функціональні вимоги. Вони можуть містити Business rules, User stories, Use cases тощо. Хорошою практикою є опис таких основних розділів:

Roles and responsibilities.
Team goals and business objective.
Background and strategic fit.
Assumptions.
User stories.
Acceptance criteria.
User interaction and design.
Questions.
Not doing.

На деяких проєктах відбувається писанина заради писанини. Інші — взагалі не витрачають ресурси на такі детальні розділи. Це й не дивно: погляньмо на два останні розділи Questions та Not doing — як взагалі можливо описати всі питання та фічі, які команда не буде розробляти?

Оскільки команда розв’язує проблеми під час реалізації проєкту X, у неї неминуче виникає багато питань. Ми почали таку практику: записували всі ці запитання та моніторили їх. Здавалося б, це нереально, але нам хотілося мати такі детальні звіти для відстежування будь-якої незрозумілої чи конфліктної ситуації. За якийсь час ми отримали результат. Але кожного разу, стикнувшись з проблемою, можна було «полистати» попередні обговорення. Зазвичай 80% вже мали рішення та були задокументовані кілька місяців тому. Так, про них просто забули чи не звернули на них уваги. А коли настала черга конкретного розгляду питання чи навіть розробки — виявилося, у команди вже є рішення!

User experience design починається на стадії вимог і проходить усі стадії розробки, охоплюючи етапи тестування та вихід в production. Процес проєктування UX містить User personas, User scenario, Scenario map, User story map, UX style guide, Site maps, Wireframes, Mock-ups, Prototypes, User flow schemes, Usability testing reports.

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

Software architecture document. Документування всіх архітектурних рішень вимагає багато зусиль. Наприклад, вирішили, задокументували, працюємо. Але реальність інша: під час розробки щось пішло не так.

З іншого боку, важко, наприклад, розробляти продукт без задокументованих Architecture & Design Principles. Якщо планували структурувати рішення за допомогою архітектури мікросервісів, то варто описати Solution details, майбутні модулі та компоненти тощо.

Quality assurance documentation. Серед найпопулярніших: Quality management plan, Test strategy, Test plan, Test case specifications, Test checklists. Якщо на вашому проєкті немає тестувальників, то й документації точно не буде. Якщо відділ тестувальників невеликий, вони зазвичай обмежуються тест-кейсами та чек-листами.

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

User documentation. Категорії User documentation також можуть розрізнятися між собою. Їх структурують відповідно до різних завдань користувача та різних рівнів досвіду. Це можуть бути end-users, support, system administrators.

Документація для кінцевих користувачів має якомога стисліше пояснити, як програмне забезпечення може допомогти вирішити їхні проблеми. Деякі частини User documentation замінюються на Onboard training. Але для складних систем необхідні User guides, Video tutorials, Wiki pages, FAQs, Embedded assistance, Support portals, etc.

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

У документах для команд підтримки зазвичай використовують Functional description, що описує функціональні можливості системи, та System admin guide, що пояснює різні типи поведінки системи в різних середовищах та інших системах, вказівки щодо вирішення різних ситуацій тощо.

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

Часто support-команді потрібно розуміти проєкт від А до Я, щоб мати змогу дослідити проблему на запит користувача. Як і в тестуванні: неможливо повністю протестувати продукт. Неможливо цілком описати продукт, передбачити всі варіанти розвитку подій, врахувати всі побажання користувача тощо.

Скільки коштує документування

Скільки коштує година роботи розробника/тестувальника над документацією? Ймовірно, стільки ж, як година розробки чи тестування. Є варіант попросити допомоги спеціального Technical Writer, який може бути як частиною команди, так і залучатися зовні.

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

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

Порахуємо загальну суму. Ви платите, наприклад, $100 на годину за 8–10 осіб, які можуть не знати всіх потрібних проєкту нюансів. Або віддаєте ті ж $100 на годину за роботу 4–5 людей, що досконало розуміють процеси. Здавалося б, більше — краще! Але ні, результат визначає не кількість людей, а такі фактори:

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

Висновок один: процес створення документації такий само ресурсно-витратний, як розробка чи тестування.

Хто крайній

Уявімо проблему на проєкті. Без належної комунікації та документації, так званих доказів, починається пошук «винних». Винними можуть бути всі, вся команда і замовник теж.

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

Але можна призначити контролюючого, який буде вести шаблони документів, пінгувати інших членів команди, дописувати самостійно, де необхідно. Хто ця людина? PM? Technical Writer? А хто володіє всебічними знаннями про продукт найбільше в команді?

Наприклад, на проєкті X настав час, коли необхідно документувати вже наявні рішення. Менеджер делегує це зовнішньому Technical Writer. Практика ця, прямо кажучи, нічого не дала. Writer гарно знав англійську мову і кілька разів на тиждень приходив в офіс, щоб розпитати про якісь деталі проєкту. За кілька місяців роботи ми отримали User guide, який далеко не все покривав. Потім його дописувала QA-команда. А з Functional documentation у Technical Writer взагалі не склалося.

Загалом знову минуло багато часу на пояснення. Відривалася від роботи команда, а в результаті — потрібно виправляти. Вихід знайшовся один: залучити QA-команду до створення документації.

Роль QA-інженера у поліпшенні продукту через документи

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

Що повинен робити QA Engineer у щоденному робочому процесі:

обговорювати ризики;
підтверджувати строки;
стежити за ранніми результатами демоверсії;
знаходити проблеми та дефекти;
допомагати з тестовими даними (для розробників).

Що має робити інженер із забезпечення якості на етапі планування:

обговорювати питання і ризики;
роз’яснювати Use cases;
визначати зовнішні інтеграції;
планувати тести для User stories;
планувати релізи з термінами виконання;
попередньо розглядати можливі проблеми/дефекти;
визначати нефункціональні вимоги.

Що повинен робити QA Engineer на етапі релізу:

тестування User stories, щоб передбачити реальні проблеми якнайшвидше та уникнути повторної роботи;
скоротити ручну роботу для тестування/швидкого тестування.

Що має зробити інженер із забезпечення якості після закінчення релізу/виходу в production:

розподілити регресійне тестування;
проаналізувати, як можна скоротити час;
синхронізуватися з автоматизованим тестуванням;
спілкуватися, щоб розв’язувати проблеми якнайшвидше (soft skills)

До чого тут документація? Загалом кожний вищенаведений пункт можна задокументувати. І це стосується не тільки тестової документації. QA-інженер як найближчий «родич» end-users бере участь у всіх процесах. Наприклад, обговорили ризики — записали в Requirement specification, а згодом у Test plan; роз’яснили Use cases — описали Test Cases document, внесли правки в сам Use case document; спланували тести на User stories — внесли правки в документ User stories; вийшли в production — уточнили User guide, Wiki, Tutorials...

Очевидно, що робота тестувальника — це не тільки тестування, а й хороша документація.

Переписати проєкт чи розібратися через документи

Як часто трапляються ситуації, коли потрібно переписати проєкт? Може, не часто. Та в мене були такі ситуації.

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

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

Отже, щоб «щось» переписати, потрібно вивчити проєкт досконало і знати кожну його деталь, мати чіткий план дій, всі вимоги, передбачувані проблеми тощо. Технічна документація повинна існувати не тільки на словах. Документація здатна допомогти в перспективі. Навіть якщо потрібно переписати частину проєкту в майбутньому.

Що я пропоную (замість висновку)

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

Командна робота передбачена у всьому: від планування до кінцевих user guides. QA-інженер має колосальний вплив на процес розробки технічної документації. Команда тестування — найближча до кінцевого користувача. Ні замовник, ні менеджери не можуть так сильно зрозуміти «біль» та «радість» від користування продуктом, який розробляє ваша команда. Тому тестувальникам не завадить мати більше контролю над документацією.

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

Щоби не пропустити нові статті Інни Козак — підписуйтеся на неї у телеграм-боті Стрічки DOU .

Опубліковано: 01/12/20 @ 11:00
Розділ Різне

SEO Блог