Комментарии 35
Ясно, понятно:
ни 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 он скрывает от юзера и таблицы выглядят таблицами. Сборка не нужна, есть ссылки и индексация текста . Есть интеграции с гит через плагины.
Столкнулись в свое время со всеми проблемами из статьи. Написали свой движок для доки:
Десктопное и браузерное приложение для редактирования. Не надо настраивать локальный сервер и пользоваться IDE: просто качаешь приложение и начинаешь писать.
Визуальный редактор с диаграммами. Чтобы не вдаваться в детали языка разметки.
Упрощенный Git-клиент в интерфейсе. Чтобы не изучать команды, а тыкать кнопки.
Комментарии для ревью. Это просто удобно.
Докер-образ для портала документации. Не нужно настраивать билд, дока обновляется автоматически.
Так что мы у Docs as Code выиграли😅 Уже несколько лет технические и нетехнические специалисты работают вместе.
Это внутренний продукт, скачать и посмотреть негде?
Добавила гитхаб в описание профиля)
О... А можно обсудить идею, которой, по моему мнению, всем подобным системам не хватает?: отслеживания зависимостей источника. Т.е.
Когда пишешь какой-то параграф, документ, итд - можно указать на основании чего (пачка ссылок в другие места набора документации, с точностью до параграфа) оно тут такое написано.
И когда там что-то меняется, система тебе подсказывает, что тебе тоже надо отревьювить и изменить уже твой текст.
Ну и все это - рекурсивно, разумеется.
О, да, была бы бомба
У нас в роадмапе есть несколько фич, которые это решат:
Трассировка требований. Можно будет связывать отдельные куски текста в рамках каталога.
Отслеживание изменений. В навигации будет показываться, какие статьи изменились или добавились.
Можем подробнее обсудить, если интересно!
Идея по реализации:
Нужны ссылки на содержание. Что-то вроде <документ>#<хэш текста параграфа>. Где-то рядом работает система индексирования, чтобы переход по таким ссылкам быстрый был. Которые просто пишутся в конце параграфа ("смотри...") и скрываются по желанию, чтобы не мешались.
Если параграф меняется - ссылка становится битой, что можно подсветить, найти скриптами итд. Но, поскольку у нас есть история - то можно найти и показать версию, когда она была верна.
Вот, собственно, и все.
Спасибо за статью. Самые ценные статьи/доклады -- про то, что не получилось, а не про то, что получилось.
Требования к системе документирования, приведенные в начале статьи, скорее ближе к wiki/confluence-подобным системам. Docs-as-code тут будет проигрывать. Понятно, все можно докрутить/перекрутить, но мы же всегда боремся со сложностью.
Если бы были требования к использованию автогенерации (когда из кода мы получаем артефакты, переиспользуемые в документации) и/или к тестированию документации (автоматизированные подходы к обеспечению ее качества), тогда можно было бы побороться за Docs-as-code. Опять же, уже в wiki/confluence этого также можно добиться, но тут уже в них сложностей будет больше.
Самая большая сложность Docs-as-code -- это, безусловно, согласование конечной документации (речь идет именно о сложной документации). Наиболее эффективный вариант здесь, кажется, -- это генерация выходного файла (файлов) в формате текстового процессора google docs/word/writer. Текстовые процессоры более менее нормально дифуют версии и позволяют удобно предлагать правки. Вы, кстати, могли бы дифовать pdf'ы, хотя это работает значительно хуже.
В любом, случае, классно, что есть статья, которая убережет от использования Docs-as-code там, где есть лучшие альтернативы.
Работаю в одном крупном банке из ТОП-10. У нас внедрили доку в коде. Большинство адекватных аналитиков это тихо ненавидят. Помимо того что этой документацией по итогу никто не пользуется, так еще и это содержит описание только микросервисов, а все остальное все равно нужно описывать в конфе. Затраты на доку в коде больше в 2-3 раза. Все кто пробовал сразу туда писать, сталкивались с проблемами. А просмотреть чужие доки из чужих репозиториев нельзя. Не мудрено, что у нас увеличилась текучка кадров, снизилась удовлетворенность. А разрабы как смотрели в конфу, так и смотрят. В общем если вы еще думаете внедрять или нет, то однозначно НЕТ! Лучше старый добрый автоматический сваггер и дока в конфе.
Как мы пытались в Docs as code и проиграли