ВЗ
что и как развернуть?
В чем он сложный и какие ограничения =)
Size: a a a
2020 May 15
L
Владислав Задумов
Предполагается что документация лежит онлайн у нас, с возможностью оперативного контент-менеджмента без пересборки документации (а-ля Конфлюенс, который у нас есть)
так если пересборка в ci ее никак не нужно специально триггерить, она просто происходит при новых коммитах, никакие пакеты никуда собирать и грузить не нужно.
L
Кто будет на KnowledgeConf 19 мая в 15-00 (МСК) заходите на островок техписов поболтать за внутреннюю документацию проектных команд: какие артефакты нужны, а какие nice to have, в чем лучше вести (вики или git-based), кто и как должен и может поддерживать.
AY
Владислав Задумов
В чем он сложный и какие ограничения =)
я сразу расскажу про ограничения H&M:
- вот там уже выше отмечают, что сложная настройка стилей и т.п.
- документация хранится в виде XML-файлов с очень сложной структурой - чтобы править, нужно обязательно ставить H&M. Если у вас люди, вовлечённые в процесс документирования, работают не с Windows, а с Linux или MacOS - всё очень усложнится;
- HTML-документация генерится с табличной вёрсткой; чтобы прикрутить свои шаблоны для HTML, нужно очень постараться;
- не очень удобный интерфейс (как мне показалось) - многие нужные операции запрятаны так, что их непросто найти;
- всё ОЧЕНЬ долго собирается (PDF может собираться 40 минут)
- вот там уже выше отмечают, что сложная настройка стилей и т.п.
- документация хранится в виде XML-файлов с очень сложной структурой - чтобы править, нужно обязательно ставить H&M. Если у вас люди, вовлечённые в процесс документирования, работают не с Windows, а с Linux или MacOS - всё очень усложнится;
- HTML-документация генерится с табличной вёрсткой; чтобы прикрутить свои шаблоны для HTML, нужно очень постараться;
- не очень удобный интерфейс (как мне показалось) - многие нужные операции запрятаны так, что их непросто найти;
- всё ОЧЕНЬ долго собирается (PDF может собираться 40 минут)
AY
это так, для начала
AY
я бы выбирал кроссплатформенный, открытый и простой в обращении инструмент
H
я бы выбирал кроссплатформенный, открытый и простой в обращении инструмент
А именно?
Что может быть проще markdown + SSG, например?
Что может быть проще markdown + SSG, например?
AY
А именно?
Что может быть проще markdown + SSG, например?
Что может быть проще markdown + SSG, например?
ну вот что-то в этом роде
AY
можно пандоком тем же всё генерировать
KU
Разработчики внезапно спросили, а есть тула, чтобы из диаграммы генерировать плантумл синтаксис) не наоборот) Встречали такое? Расширений для коде и онлайн эдиторов,делающих обратное для превью куча.
А что они пытаются так решить?
Генерация кода из uml-диаграмм вроде большинством языков программирования покрыта. Почему именно PlantUML?
Генерация кода из uml-диаграмм вроде большинством языков программирования покрыта. Почему именно PlantUML?
KU
Владислав Задумов
Раньше писали в Конфлюенсе, вариант немного сомнительный, так как предполагается параллельное развитие и поддержка нескольких версий проекта, а версионирование в конфлюенсе только на уровне пространства
Вот неплохая подробная статья про pages и их настройку: https://medium.com/nuances-of-programming/как-создать-бесплатный-сайт-на-github-pages-e0f3c258ee22
ВЗ
Вот неплохая подробная статья про pages и их настройку: https://medium.com/nuances-of-programming/как-создать-бесплатный-сайт-на-github-pages-e0f3c258ee22
Спасибо, почитаю =)
L
А что они пытаются так решить?
Генерация кода из uml-диаграмм вроде большинством языков программирования покрыта. Почему именно PlantUML?
Генерация кода из uml-диаграмм вроде большинством языков программирования покрыта. Почему именно PlantUML?
Они рисовать диаграммы хотят, чтобы объяснить как сервис работает, а не код генерировать из них
А
Владислав Задумов
Предполагается что документация лежит онлайн у нас, с возможностью оперативного контент-менеджмента без пересборки документации (а-ля Конфлюенс, который у нас есть)
HM - это десктопное приложение. После правки контента, вам придется пересобрать сайт.
ЕД
Плюсую про HUGO. Один раз настроил конвейер, который собирает и деплоит сайт, и потом работай с доками хоть в Typora
ЕД
Сохранил, коммит - и все через пару минут актуализовано
FM
Попробуйте oxygenXML
НН
Не пробуйте
НН
Плохой совет
FM
пробуйте, хороший совет.