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

Що було найціннішим надбанням, яке дослідники давнини привезли додому зі своїх подорожей? Золото і прянощі? неправильно. Карти.

Христофор Колумб ніколи б не здійснив свою знамениту подорож у 1492 році без карта розроблений його попередниками. Шпигунська гра для отримання португальських карт заклала основу Голландської Ост-Індської компанії, можливо, найдорожчої компанії в історії людства. На піку свого розвитку в 1637 році він коштував 78 мільйонів голландських гульденів, що еквівалентно 7,9 трильйонів доларів в доларах 2017 року. Це більше 10 трильйонів доларів у 2024 році, більше, ніж Microsoft , Nvidia та Apple комбіновані . Відчутні скарби з нових земель були важливими в короткостроковій перспективі, але в довгостроковій перспективі саме знання створювали справжні статки.

Чому в сучасному світі технологій ми забуваємо про це? У гонитві за негайним успіхом ми часто не бажаємо витрачати дорогоцінний час і ресурси на створення та підтримку технічної документації. Говорячи термінами 17-го століття, ми поспішаємо захопити золото та прянощі, не будуючи своїх карт, які, у свою чергу, могли б привести нас до набагато більшої кількості золота та прянощів. Ви налаштовані скептично? Ой, давайте подивимося ближче…

Дикий код

— Як ви, мабуть, пам’ятаєте, гіпноїдний стаз нейронних патернів мозку можна просканувати додатковим електромагнітним променем, який… — «Відчепись!» — нетерпляче сказав Ард Варк. "Що ви маєте на увазі - як ми, безсумнівно, пам'ятаємо?" Як ми можемо це пам'ятати, коли ми ніколи цього не знали? – Ця цитата з оповідання видатного письменника-фантаста Едмонда Гамільтона «Wacky World» стосується марсіан, а не програмістів. Однак багато людей дивляться на розробників так, ніби вони з іншої планети, особливо ті, хто має лише туманне уявлення про розробку програмного забезпечення та її складності. Справа в тому, що розробники часто вважають, що інші знають код так само добре, як і вони, і часто вважають технічну документацію непотрібною. Таке мислення ризикує зробити проект таким же складним і незрозумілим для сторонніх, як «гіпноїдний застій», що зрештою ставить під загрозу потенційний успіх проекту.

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

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

Bus factor, Burnout та інші фантастичні звірі

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

Історія №1: Неможливість масштабування

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

Історія №2: Проблеми з обслуговуванням

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

Історія №3: Вигорання розробника

Проект "SmartestEver" зіткнувся з серйозними проблемами, тому що його головний розробник Ендрю, який займався майже всім, звільнився після того, як його команда засипала численними запитаннями. Якби «SmartestEver» мав відповідну документацію, молодші розробники могли б легко звернутися до розділу поширених запитань і вирішити рутинні проблеми. Натомість вони засипали Ендрю запитаннями, і без нього та необхідної документації команда просто не змогла продовжити роботу, і проект було закрито (натисніть F для Ендрю).

Історія №4: Фактор автобуса

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

Історія №5: Жодного пророка не вітають у відкритому коді

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

Від юнги до капітана

Гаразд, у нас є трохи теорії та практики, а тепер зануримося в дослідження та статистику. Опитування розробників Stack Overflow 2024 держави що 84% респондентів використовують технічну документацію для розуміння функціональності технологій. Однак, навіть маючи документацію, вони часто не можуть знайти відповіді, які їм потрібні, про що свідчать наступні за популярністю ресурси: Stack Overflow (80%), Written Tutorials (68%), blogs (61%) і How-to відео (54%). Microsoft Research: Щоденне життя розробників програмного забезпечення знайдено що в середньому розробники витрачають 1-2% свого дня (8-10 хвилин) на документацію, а 10,3% розробників кажуть, що застаріла документація змушує їх витрачати занадто багато часу на самостійний пошук відповідей. Необхідність документації також викликає серйозне занепокоєння для академічної спільноти. Простий пошук Google Scholar для <"документація" І "програмне забезпечення"> врожайність понад 4 мільйони результатів, що чітко вказує на величезну кількість наукових публікацій, присвячених цьому питанню.

Основні висновки напрочуд прості: №1 – Кожному потрібна документація, коли справа доходить до розуміння техніки та/або роботи інших людей; але №2 – Мало хто турбується про написання та підтримку цього; і, як наслідок, №3 – багато документації написане погано, застаріло та взагалі марно. Отже, що потрібно зробити? Змініть свою мотивацію на всіх рівнях.

Група дослідників з Університету прикладних наук HAN та Університету Гронінгена (обидва в Нідерландах) ідентифіковані найбільш типові проблеми з технічною документацією:

• Неформальну документацію, якою часто користуються розробники, важко зрозуміти;

• Документація вважається відходами, якщо вона не сприяє негайному створенню кінцевого продукту;

• Продуктивність розробника вимірюється лише кількістю робочого ПЗ;

• Документація часто не синхронізована з фактичним програмним забезпеченням;

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

  
  

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