привіт Нікіта
можливо можеш трохи допомогти?
Треба інструмент котрий міг би полегшити документацію. Confluence не має. На данний момент вся документація створюється в окремому git проекті. Шо не є зручно.
Є купа репозиторієв в котрих є свої нюанси (як приклад як додавати переклади, сетапити перший запуск ...). Readme не дуже зруно юзати.
Можливо знаєшь якість інструменти? можливо якийсь npm пактет котрий міг би давати змогу вести зручну документацію для кожного репозиторія?у клієнта Azure інфраструктура
привіт
1. як я тебе зрозумів
- є система (або група застосунків), код якої зберігається як polyrepo
- є технічна документація, що зберігається в окремому репозиторії
2. як я зрозумів проблему — неактуальність документації. Вона частково спричинена тим, що зміни в репозиторіях app1/appN із кодом не завжди супроводжуються змінами в репозиторії з документацією docs
3. що я припускаю за контекстом
- використовується GitHub Actions
- проблему не вдається вирішити використовуючи тількі інженерну дисципліну
4. що б я зробив
- продовжив би використовувати один репозиторій для документації як джерело правди
- додав би в кожен репозиторій папку docs
- створив би reusable GitHub Action, який копіює зміни з appN/docs у docs/appN
у результаті розробники відповідають за документацію на рівні репозиторію, а архітектори — на рівні docs
5. опційно
- для людей із репозиторію docs зробити автопублікацію сайту з документацією (є багато готових рішень для перетворення markdown → HTML)
- вибрати й задокументувати технічний стек у репозиторії docs, додати скрипти для перевірки відповідності у всіх репозиторіях (наприклад, версія TypeScript/Eslint/etc)
- реалізувати підхід для генерації специфікацій із коду (Swagger чи його аналоги) і збірку зі всіх репозиторіїв
- для AI coding agents — створити власний MCP сервер. Спочатку з документацією, пізніше з метриками з інфраструктури й даними з застосунків
А взагалі ведення узгодженої документації — це більше про допомогу людям домовитися й дотримуватись домовленостей, ніж про інженерію.