Комментарии 24
Ясно, понятно:
ни Hugo, ни Gitea не
Спасибо, gitlab и confluence тогда отлично подходят - оба поддерживают asciidoc
Соответственно если бы разработчик решил читать документацию в IDE, то первая же ссылка перебросила бы его в Hugo.
Как-то я не понял workflow. Готовое приложение никто же не смотрит в виде исходников - смотрят на какой-то экземляр, запущенный на каком-то тестовом стенде. Соответственно, документацию-как-код тоже не нужно смотреть в виде исходника тем, кто ее не пишет - все ее пользователи должны смотреть на собранный вариант конкретной ветки.
Т.е. выглядит так, что проблемы возникли в значительной степени из того, что решили 'настраивать сборку Hugo для каждой ветки эпика нецелесообразно.' Собственно, не очень понятно, в чем проблема собирать из любой ветки, какую залили в систему сборки.
Не целесообразно даже тратить ресурсы на сборку, потому что документация ветки конкретной фичи интересна примерно никому, как и исходники. Разве что для QA в момент тестирования пригодится. В остальном даже разработчики предпочитают иметь ввиду целевое решение и будущие смежные доработки.
документация ветки конкретной фичи интересна примерно никому, как и исходники
Простите, а ревью?
Не целесообразно даже тратить ресурсы на сборку, потому что документация ветки конкретной фичи интересна примерно никому, как и исходники.
Все равно не понял. Как это может выглядеть:
Вот есть некая фича на реализацию. По ней готовят документацию в какой-то ветке. Тот, кто это документацию пишет в какой-то то момент делает push исходников этой документации. Оно подхватывается pipeline сборки и заливается в каой-то стенд. И в результате разработчик смотрит на https://stand-1../docs/..../Feature-XYZ.html, пишет замеченные дефекты и замечания в бэг-трекер в сторону писателей, они их исправляют и цикл повторяется, с обновлением стендов.
А у вас как? Разработчик смотрит непосредственно в исходный код доки, пытается понять, что из него получится и пишет замечания при помощи системы Code Review прямо по исходникам документации?
документация "сверху" (как хотят) -- в конфлюенсах и вордах, а документация "снизу" (как есть) -- в репах и маркдаун. пока так практикуем.. вроде норм.
PS: только plantUml сильно серьезно, в итоге оказалось, зато mermaid выручает быстро накидать схему, что происходит, какие-небудь sequence diagram и т.п.
С вашим стеком не работал, но расскажу как решали некоторые подобные проблемы у себя:
Отображение диаграмм: мы рендерили диаграммы в png в GitHub actions.
Ссылки: вообще документы должны ссылаться на соответствующий документ в репо, а не на воображаемый в Hugo. На нашем стеке ссылки автоматически преобразовывались плагином в пайплайне при переливке в базу знаний.
То, что «сложна, непонятно и глазки болят» тут уж извините…но тот классический свинарник, который устраивают аналитики в базе знаний тоже «сложна, непонятно и глазки болят» и хрен что найдешь потом (без негатива).
Комменты по ошибкам надо оставлять на ревью в ПР, либо, если найдено пост-фактум, заводить issues в репозитории на конкретный файл и строчку и тэгать аналитика.
Про gitea ничего не знаю, но гитхаб и ide нормально отображают документы в md и asciidoc, поэтому чаще всего никакие Hugo в целом не нужны были, только для смежников (у нас была интеграция в confluence увы ныне почившая).
Поломки сборки: при создании ПРа должна проводиться автоматическая упрощенная версия сборки в ci/cd. Если не собралось - ПР блокируется.
я большой сторонник doc as a code, при нормальном ci/cd и адекватных разработчиках и аналитиках документация получается супер, хотя конечно не панацея и испортить можно все что угодно.
В противовес был у меня проектик где дока хранилась и в репо, и в Миро, и в базе знаний, и в тикетах, чатах и бог знает где еще. Разумеется актуальной она была нигде. Вот это ад.
Соответственно если бы разработчик решил читать документацию в IDE, то первая же ссылка перебросила бы его в Hugo
Что? Почему? С каких пор статически сгенерённый сайт что-то знает про то как запускать генератор?
Поверьте, заполнение таблички с WYSIWYG резко отличается от контроля количества вертикальных палочек в строке 213
Ну, если использовать так себе редактор, потому что отказались от родного Markdown (которого почему-то хватает чувакам из Kubernetes), то бывает.
в каждой папочке Hugo должен лежать index-файл этой папочки
Надо бы разобраться, зачем вам каждая папочка и файл в этой папочке и как они друг на друга ссылаются на самом деле. Потому что на самом деле такой необходимости нет.
ни Hugo, ни Gitea не поддерживают AsciiDoc из коробки
Ёжики кололись, но продолжали не читать документацию при разработке документации
В Hugo нельзя просто выделить текст с ошибкой и написать к нему комментарий
Хостится в репо, все приличные ребята оставляют в углу ссылку на репо, народ идёт в репо и заводит там либо ишую, либо комментит конкретное место в коде
1) Сайт про генератор ничего не знал. А генератор не знал, как из относительных ссылок в репозитории или из url до репозитория сделать ссылку, которая подходила бы hugo. Однако аналитик вполне мог установить адрес будущей страницы в hugo, их и ставили сразу в документ.
2-4) Почему все копипастят "не поддерживают"? Там дальше выделенное "в полной мере". Ну типа здорово предположить, что мы не читали документацию, читая статью по диагонали.
5) Да, это решение. Но сравните количество действий между ним и "выделил-тегнул". Плюс обучение не только аналитиков (с ними-то намучилась), плюс разграничение доступов к репозиториям...
В общем, мне не кажется хорошей идея выполнять простые действия сложными путями при наличии специализированных средств. Выигрыша от гита мы не получили, сравнением версий разработчики пользоваться не стали, в том числе потому, что изменения у нас обычно радикальные. Исходные гипотезы не подтвердились и нашей команде Docs as Code не подошёл.
Hugo кастомизируется в доль и поперёк, а где не кастомизируется Hugo, там к статике прикручивается js, но идея про "выделил-тегнул" вполне себе делается в таком ключе
Hugo - генератор который ориентирован на Markdown в первую очередь. И его успешно юзают в достаточно больших проектах. Про п.3 не очень понятно что именно "в полной мере". Я в Markdown могу ссылаться на документ как на "мой-проект/моя-супеклёвая-статья/index.md", так и на "мой-проект/моя-супеклёвая-статья.md" и большой разницы не увижу. Удобно складывать всё прям в отдельную директорию только если ВСЕ ресурсы статьи (картинки, SVG с диаграммами и т.д.) хотите держать в директории со статьёй и с ней же регулярно переносить не привязываясь к путям проекта. Тот же Obsidian при правильной настройке нормально будет делать ссылки вот прям по [[ с подсказками и нормальным вузивугом для людей дёшево, без IDE и с синхронизацией в Git. В основном index в поддиректориях проектов нужен, чтобы иметь какой-нибудь кастомный вид для страницы содержащей список статей в данной категории или ещё какую-нибудь отсебятину на уровне выше чем сами документы.
Главное первый раз под себя тщательно настроить, как Hugo, так и Obsidian (и поотрывать всякие "красивые" wikilinks, собственное видение переносов строк, хранение всего-всего в корне - тогда это будет честный Markdown и его можно будет без проблем редактировать в чём угодно)
Спасибо. Я не сомневаюсь в возможностях Hugo касательно Markdown. Наверное, и для Asciidoc его можно годно кастомизировать, чтобы не извращался над таблицами. Наверное. Но у нас не было времени и свободных рук, чтобы это выяснять. Поэтому и пишу — в полной мере из коробки не поддерживает.
Конкретно: в превью документа видим красиво отформатированную таблицу в соответствии с туториалом Аскидока, в хьюго таблица уезжает за границу экрана без возможности горизонтальной прокрутки и выравнивает столбцы, как захочет.
Но это всего лишь эстетика. Может быть, ею и занялись бы когда-нибудь, если бы нам удалось выстроить процесс согласования. Провалились мы на нём.
. Выигрыша от гита мы не получили, сравнением версий разработчики пользоваться не стали, в том числе потому, что изменения у нас обычно радикальные.
Это становится нужным потом. Лет через несколько, когда у кого-нибудь встает вопрос ' Нам кажется, что то что есть - это вроде неправильно. Кто и почему вообще захотел так сделать?'
И начинается копание в истории, после которого выясняется, что то что сделано - это последовательные изменения тогда-то, тогда-то и тогда-то. И то что 'правильным' - это уже 4-й раз запрашивается и на самом деле работать не будет.
Это понятно, но та же история есть в конфлюенсе. А качественную трассировку версионирование само по себе не обеспечивает, к сожалению. Трассировку обеспечивает только чистоплотность человека, который вносит изменения.
Гипотеза была в том, что, работая над задачей, разработчик будет смотреть дельту изменений по ней. Но нет, разработчики предпочли смотреть только итоговую доку.
Но нет, разработчики предпочли смотреть только итоговую доку.
Я про то, что дельту будут смотреть не в момент разработки. А вот когда-нибудь потом - инженеры (и программисты в том числе) поддержки, когда будут разбираться с вопросами "что тут у нас происходило и как мы пришли к тому, что у нас имеется".
Что-то git-образное позволяет, скажем git bisect-ом ответить на вопрос "А в какой версии софта мы это требование в таком виде изложили?". А в том виде, что у confluence - это часто невозможно, потому что документация для приложения v1 лежит отдельно от документации к v2 (потому что нужно обе одновременно) и у страниц просто нет общей истории. Да и поиск, где именно изменения внесли - руками, перебирая версии.
Я поняла. Я говорю о том, что спустя N лет дельту изменений можно посмотреть и в гит, и в конфлюенс. Причина изменений и там, и там будет указана только в том случае, если её не забыли указать при коммите/сохранении.
То есть есть при выборе между этими системами историчность сама по себе бонуса не даёт.
И мы хотели иметь плюшку от дельты непосредственно в момент разработки и непосредственно в IDE, чтобы разработчику даже не приходилось её сворачивать и смотреть документацию где-то ещё. И вот это не стрельнуло.
Это не в специальном редакторе редактируется, а с тегами ручками пишут?
А редакторы базы знаний типа Obsidian никто не пробовал использовать? Исходник md он скрывает от юзера и таблицы выглядят таблицами. Сборка не нужна, есть ссылки и индексация текста . Есть интеграции с гит через плагины.
Как мы пытались в Docs as code и проиграли