У кримінології існує теорія розбитих вікон: «Якщо в будівлі розбите одне вікно і його ніхто не помічає, то через деякий час не залишиться жодного цілого вікна». Згідно з цим, якщо не підтримувати порядок, люди більш охоче його порушують і «забивають» на правила.
Під час розробки IT-проєктів важливо вести документацію та стежити за тим, щоб у ній був порядок. Саме на неї дивляться, щоб зробити висновки щодо проєкту. А ще це ваш захист на випадок, якщо щось пішло не за планом. Розібралися з Technical Program Manager у Booking.com Тарасом Федоруком, навіщо в IT проєктна документація та як її вести, щоб знизити ризики під час розробки.
Тарас — президент українського представництва PMI. Пройшов понад 10 професійних сертифікацій, зокрема PMP (Project Management Professional) та PSM ІІ (Professional Scrum Master ІІ). Отримав нагороди «Найкращий керівник проєктів в IT» за версією Ukrainian IT Awards у 2019 році та PMI Rising Leader у 2022.
*Скоро у Тараса стартує онлайн-курс у Laba «Проджект-менеджмент в IT».
Що таке проєктна документація та навіщо її готують
Завдання на розробку починається з ідеї. Щоб щось створити, спочатку це потрібно уявити. Щоб не втратити думки, краще зафіксувати їх у вигляді тексту або графічно. Фактично проєктна документація — це процес опису ідеї від моменту її виникнення до випуску результатів у реліз.
Пізніше, упродовж проєкту, документація розширюється не лише завдяки інформації про продукт, а й про процес. Іншими словами, ми відповідаємо на запитання «Як?» — як комунікувати, звітувати, працювати з якістю тощо. Обсяг документації залежить виключно від того, яку проєктну інформацію потрібно зберегти та наскільки легко її потім можна отримати.
Багато бізнесів недооцінюють важливість внутрішньої документації, поки нормальний перебіг процесів не порушить непередбачувана ситуація. Згідно з дослідженнями, лише 4% компаній завжди документують внутрішні процеси. Ще 50% визнають, що займаються цим час від часу.
Що дає проєктна документація в IT:
- Менше обговорень у командних чатах та пошуків причин «чому так, а не інакше»
- Швидше занурення у контекст
- Простіше розуміння та оцінка обсягів змін
- Простіше ухвалення управлінських рішень (наприклад, розуміння того, який сервіс можна прибрати та як це відіб’ється на всій системі)
- Можливість комплексно оцінити IT-структуру та вчасно помітити помилки або пробіли в архітектурі
- Можливість комплексної оцінки перебігу проєкту: що з процесів ефективне, що — зайве (і чому), що треба покращити
З мого досвіду, 80–90% проєктів реалізуються без суттєвих проблем чи питань з боку клієнта. Він навіть може не вимагати наявності технічної документації (проте це не значить, що її не потрібно вести).
Водночас у решті IT-проєктів фінансові втрати через відсутність ретельно складеної проєктної документації можуть сягати сотень тисяч доларів. Завжди є та будуть клієнти, з якими проєктна документація стане рятівним жилетом на випадок, якщо щось піде не за планом.
Що може статися, якщо не вести проєктну документацію
Якось я працював на проєкті, де не було конкретних стандартів документації. Її ніхто не вимагав і не перевіряв, проте я завжди готую документацію.
Наша команда працювала над двома фазами проєкту: discovery та власне розробка. З клієнтом підписали контракт, де було чітко вказано, який функціонал ми маємо розробити.
Команда провела дослідження, після чого підготувала звіт, як саме реалізує задачу та який бюджет на це треба виділити. Під час погодження замовник попросив додати до IT-системи функціонал, який ми не обговорювали на старті. Тоді ми оцінили, скільки це коштуватиме. Але у клієнта не було стільки часу та бюджету на додаткові функції. Щоб не гаяти часу, ми почали працювати над функціоналом, погодженим у контракті.
Через 5 тижнів клієнт повернувся та розірвав договір. У контракті була прописана компенсація на такий випадок — замовник не міг просто вийти з проєкту. Але він поставив пряме запитання: «А чим ви займалися ці 5 тижнів? Як я можу бути впевненим, що ви справді працювали над проєктом?»
У таких ситуаціях статут проєкту, щотижневі звіти, план фаз проєкту та інші документи рятують команду від перспективи залишитися «біля розбитого корита». Ми мали необхідну проєктну документацію, тож клієнт виплатив компенсацію за розірвання договору і не став звертатися до суду (як обіцяв, поки ми не показали IT-документацію).
Які бувають види документації на проєкті
Усю документацію можна розділити на дві категорії:
- 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
Це живі документи, призначені для внутрішнього використання: Management plans, Playbooks, Baselines, Charters, Checklists, Reports тощо. Документація процесів усуває плутанину. Це основний ресурс з інструкціями про те, як виконати те чи інше завдання.
7 принципів створення проєктної документації в IT
На курсі я розповідатиму, як правильно оформити проєктну документацію, а зараз — кілька інсайтів про стандарти складання й те, що має бути в документації проєкту.
#1. Дотримуйтеся однотипної структури
Кожен документ повинен мати структуру: заголовок, назва проєкту, автор, історія змін, хто підписав документ і коротке intro, в якому описуємо мету існування кожного документа. До прикладу, типове інтро для статуту проєкту може виглядати так:
«Статут проєкту служить базовою угодою між командою проєкту та стейкхолдерами стосовно мети проєкту, основних обмежень та контексту проєкту. Документ буде використаний як основа для подальшої деталізації проєктного середовища та слугуватиме джерелом основної інформації для ухвалення рішень».
#2. Пишіть просто і зрозуміло
Технічна документація може мати різний вигляд: бути оформлена в Microsoft Word, у формі таблиці, дизайн-системи у Figma чи дерева у Confluence.
Але правило для всіх форматів одне: пояснюйте все простою мовою, уникайте скорочень і заплутаних фраз. Виділяйте підзаголовки та марковані списки, щоб документ можна було легко переглядати й швидко знаходити потрібне.
#3. Використовуйте схеми та діаграми
Візуальна інформація сприймається легше та швидше, а також краще запам'ятовується. Чим більше даних ви надасте графічно, тим доступнішою та коротшою буде документація. Я зараз спостерігаю поширення популярності Google Slides та інших програм для створення презентацій — якраз із цієї причини.
#4. Використовуйте в документації елементи, з яких складається проєкт, навіть якщо немає можливості гарно їх оформити. Такими елементами можуть бути, наприклад, листи з домовленостями, приклади даних і посилання. Інакше ви просто забудете, що таке колись було. А якщо необхідно буде підтвердити інформацію, не доведеться витрачати годину на пошук потрібного листа чи повідомлення.
#5. Забезпечте зручний доступ до документації
Я не прихильник того, коли вся проєктна інформація збирається в одному Excel-документі, де є купа вкладок із розкладом, ризиками, принципами комунікації тощо.
Розділення документів, а не оформлення в одному, — це зручно. А ще допоможе легко обмежити доступ до sensitive інформації для певних осіб, якщо така потреба виникне. Наприклад, ваш Регістр Стейкхолдерів містить детальну інформацію про те, як ви плануєте залучати їх до проєкту. Тоді буде ніяково, якщо колеги почнуть читати про ваші плани провести неформальну зустріч або привітати їх із Днем народження.
Також усі документи мають просто та однотипно називатися. Якщо це статут — його треба оформити окремо й дати відповідну назву, наприклад:
projectX_project-charter
Називаючи файли, підходьте з позиції своїх колег і клієнта, які намагатимуться знайти потрібну інформацію. Прості та недвозначні формулювання значно скоротять час на пошуки. Користуйтеся визнаною у вашій організації термінологією, не називайте статут проєкту «брифом», якщо так більше ніхто не робить.
#6. Розвивайте культуру документування в команді
Не обов'язково все має документувати одна людина. Наприклад, статут — це відповідальність керівника проєкту. Водночас технічну документацію мають створювати архітектори або Senior/Lead-розробники, стандарти тестування — QA Lead, User Guide — технічні райтери.
Тож важливо пояснювати важливість ведення проєктної документації в команді, навчати людей, як це робити, та сприяти тому, щоб вони складали свої артефакти.
#7. Закривайте техборг
Виділяйте час на дооформлення «хвостів» — інакше клієнту або іншій команді не бачити доопрацювання системи без стресів. Уявіть, що ви приходите на цей проєкт зараз і ніхто з попередників із вами поспілкуватися не зможе.
Пишіть документацію так, щоб проєкт можна було легко та безболісно передати іншій команді.
Бажаєте отримувати дайджест статей?
