Чему учиться в эпоху ИИ?
Заметка по книге Букреева и ДеУолта “Эверест. Смертельное восхождение”
Почти два года назад я рассказывал вам про ведение документации проекта на Markdown, когда файлы документации располагаются рядом с исходным кодом. То есть в том же репозитории.
Но, честно говоря, мне было непонятно, как это заработает на большом объеме. Одно дело - запилить десяток файлов, и совсем другое - поддержать полноценную документацию.
И тут попадается живой пример!
Копаясь в проекте Capella на GitHub, я обратил внимание на довольно развитый раздел Wiki. На первый взгляд, ничего особенного, у многих такое есть. Но при переходе по первой же ссылке я попадаю обратно в репозиторий!
GitHub Wiki оказалась фасадом, который ведет к файлам документации, расположенным в основном репозитории. И этих файлов там больше трех сотен.
В Capella вместо Markdown используется MediaWiki. Они похожи. В обоих случаях культивируется парадигма “doc as code”. Однако MediaWiki посложнее и предлагает больше инструментов для разработки документации. Но самое главное, что GitHub “из коробки” умеет рендерить и те, и другие файлы.
Я не знаю, насколько наличие документации мешает работе с репозиторием. Ну git clone будет выполняться подольше. Ну места на диске будет занято чуть больше…
С другой стороны:
- документация всегда под рукой,
- как следствие, поддерживать ее проще,
- как следствие, правки кода и документации попадают в один пул-реквест,
- как следствие, сборка с пул-реквеста готова в production.
В общем, подход имеет место быть. Проект Capella не заброшен и развивается. 5000+ коммитов, ежегодные релизы, полсотни контрибьюторов говорят сами за себя.
Свежие записи
Работать долго
Заметка по книге Нассима Талеба “Одураченные случайностью”
Doc As Code: диаграммы PlantUML в Doxygen
Включаем поддержку UML-диаграмм в Doxygen и размышляем о последствиях
Какие файлы нельзя коммитить в Git
Разбираемся, как не превратить репозиторий Git в Google-диск
Зачем нужны UML диаграммы?
Выясняем, когда и для чего разработчики используют UML