Стендап Сьогодні 📢 Канал в Telegram @stendap_sogodni

🤖🚫 AI-free content. This post is 100% written by a human, as is everything on my blog. Enjoy!

19.12.2022

Документація процесів як неодмінна частина розробки

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

Я б розказав більше, але то справжнє ноу-хау, якого (наскільки я знаю) ні в кого на світі більше немає, тому ніяк не можу. А як воно здобувалось… це був скажений тиждень перебору розвʼязків та навіть напрямків — коли успіх всього проєкту залежав від однієї-єдиної ключової ділянки.

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

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

А далі, в ідеалі, кожне розʼяснення архітектури має закінчуватись новою главою документації. Таким собі внутрішнім RFC для команди. (Та, закладаюся, OpenAI з таким твором не впорається.)