Май в DocOps чате

Это краткое резюме дискуссий и полезных ссылок в чате Docops в мае 2020.

Построение диаграмм из кода/текста: когда подходит, а когда нет

Лицензии на общедоступные темы для статических сайтов

Выбор решения для деплоя и хостинга сайта с документацией

Упомянутые инструменты: Sphinx, Netlify, Hugo, Jekyll, Antora, Foliant, surge.sh.

08.05

Доброго дня! Подскажите для VS code плагин для превью MD файлов

• https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles
• Markdown Preview Enhanced

12.05

@olegkovalov поделился ссылкой на сервис, который позволяет строить архитектурные диаграммы как код/текст: https://structurizr.com/

• Далее длинная дискуссия на тему, когда уместно версионировать и генерировать диаграммы, а когда проще использовать Draw.io (и аналоги). Начиная отсюда и ниже: https://t.me/docsascode/14571
• Диаграмму можно кодом запилить (например, d3.js). Будет и версионирование, и схемы произвольной сложности – только вот порог вхождения несоразмерный)

13.05

Разработчики внезапно спросили, а есть тула, чтобы из диаграммы генерировать плантумл синтаксис) не наоборот) Встречали такое? Расширений для коде и онлайн эдиторов,делающих обратное для превью куча.

• они ж нарисуют такого что и не будет преобразовываться)

Ссылка на лекцию про построение инфраструктуры docops, на примере Foliant: https://youtu.be/6CKVodl2YcA

15.05

Подскажите пожалуйста инструменты для написания документации с не особо высоким порогом входа в плане инфраструктуры. Получили новый проект, для него нужно практически с нуля оформлять документацию с процессами, вот и собираем варианты.

• Зависит от того, в чем у вас уже есть экспертиза, во что не нужно вхождение, может есть у разработки уже какие-то инструменты
• Без своей инфраструктуры можно поднимать gitlab/github pages, к первому много готовых паков под разные ssg, по сути от вас только нужно gitlab-ci.yml заполнить или взять готовый
• Hugo
• @ushkatia Вот неплохая подробная статья про pages и их настройку: https://medium.com/nuances-of-programming/как-создать-бесплатный-сайт-на-github-pages-e0f3c258ee22
• Плюсую про HUGO. Один раз настроил конвейер, который собирает и деплоит сайт, и потом работай с доками хоть в Typora
• Здесь можно посмотреть примеры статических сайтов, сделанных генераторами типа хьюго: https://jamstackthemes.dev/
• ...вот сайт с документацией, у которого исходный код лежит в гите: https://docs.cloudify.co/ Вот их репозиторий https://github.com/cloudify-cosmo/docs.getcloudify.org Скачиваете и переделываете тему под себя

Ограничения Help&Manual

• @ayemelianov вот там уже выше отмечают, что сложная настройка стилей и т.п.

- документация хранится в виде XML-файлов с очень сложной структурой - чтобы править, нужно обязательно ставить H&M. Если у вас люди, вовлечённые в процесс документирования, работают не с Windows, а с Linux или MacOS - всё очень усложнится;

- HTML-документация генерится с табличной вёрсткой; чтобы прикрутить свои шаблоны для HTML, нужно очень постараться;

- не очень удобный интерфейс (как мне показалось) - многие нужные операции запрятаны так, что их непросто найти;

- всё ОЧЕНЬ долго собирается (PDF может собираться 40 минут)

17.05

Может, кто-то знает больше о юридических аспектах использования всех этих тем для статических сайтов, которые выложены в общем доступе в гите?

• Creative Commons - семейство лицензий, ориентированных в первую очередь на медиапродукцию, а не на ПО.
• Dima Boger: А гитхаб старается понятным языком описывать свойства лицензий, особенно если он их узнаёт
• https://github.com/tlbootcamp/tlroadmap/blob/master/LICENSE.md
• @SuckMyNuts https://tldrlegal.com/: На сайте собраны всевозможные software лицензии (GPL, MIT и т.д) описанные максимально простым языком, который понимают все, а не только юристы
• @b0g3r: Нужно чётко понимать, что не всё что лежит на гитхабе или есть в интернете общедоступно для использования и переиспользования. У каждой штуки есть лицензия, а если её нет, то лучше её не тащить, или хорошенько посчитать риски У нас в компании юристы подготовили вайтлист и блеклист лицензий, которые мы можем тащить как зависимости во внутренние продукты. Мы сверяемся 🤷‍♂️

19.05

Подскажите, можно ли в mermaid сделать диаграмму наподобие вот этой? https://dreampuf.github.io/GraphvizOnline/#digraph%20G%20%7B%0A%0Aconnection2%20-%3E%20root%20%5Blabel%3D%22from%22%5D%3B%0Aconnection1%20-%3E%20root%20%5Blabel%3D%22from%22%5D%3B%0Aconnection2%20-%3E%20leaf%20%5Blabel%3D%22to%22%5D%3B%0Aconnection1%20-%3E%20leaf%20%5Blabel%3D%22to%22%5D%3B%0A%7D

• https://mermaid-js.github.io/mermaid-live-editor/ Проверить можно тут
• я как раз там и пробую. у меня не получается то, что я хочу. Я не могу сделать стрелку "против хода" (пример a --> b & c--> d). либо узлы "connection" группируются друг с другом (как в примере с graph TB A & B--> C & D), а мне нужно расположить их так, чтобы стрелки не пересекались

20.05

Как вы деплоите свои статические сайты? Я вот задался целью найти сервис, чтобы можно было деплоить файлы HTML из гугл диска, дропбокса, гита и других облачных хранилищ без лишнего гемора. И вот описано, как это сделать:

• https://www.freecodecamp.org/news/how-to-deploy-a-static-website-for-free-in-only-3-minutes-with-google-drive/
• как все остальные сервисы в компании - gitlab ci, docker, nginx, kuber, инфре так проще, всем все одинаково
• Кстати, я ещё юзаю surge.sh Это вообще верх минимализма никаких админок, ничего — просто npm пакет, которому скармливаешь сабдомен или домен, папку, которую надо задеплоить и 💫https://www.youtube.com/watch?v=-EjdMvYPSVU
• on a side note, находил недавно докер контейнер который скрэппит весь тильда сайтик и хостит где хочешь в редисе и с ssl и всяким таким

22.05

Коллеги, а есть какой-то гайд в докопс-тулинг?

• У меня внезапно коллеги-девопсы проснулись и открыли для себя plantuml, хочу им подсунуть всё остальное
• https://www.staticgen.com/ если про выбор тула А вот про цепочку тулов https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html#integrating-into-engineering-tools-and-workflows

25.05

Коллеги, а кто-нить использовал plantuml с draw.io (рендер кода plantuml в draw.io)? Я устал от конфлюшных sequence-diagram, там ничего нет почти (ветвлений, комментов, циклов, you name it) и они не ресайзятся по горизонтали, т.е. убивают вёрстку сгенерённой страницы...

• в конфлюшной нужно указывать/развёртывать plantuml-сервер, внешний не дадут, внутренний небось тоже UNSUPPORTED будет, а десктопная версия вообще не может plantuml отрендерить... "Unknown error", когда пытаештся апдейтнуть существующую диаграмму, и отсутствие пункта меню "PlantUML" вообще в новой диаграмме...
• мермаид хорош для редактирования текстом. Ещё есть на питоне его аналог

28.05

https://slides.com/seldo/jamstack-survey-2020#/

https://www.youtube.com/playlist?list=PL58Wk5g77lF8jzqp_1cViDf-WilJsAvqT

Интересный анализ от Netlify. В том числе по генераторам статических сайтов. Больше всего опрошенным понравился 11ty. Кто-то пользовался этим?

31.05

Выбираю систему для документации пользователя по продукту. Посоветуйте что сейчас стоит использовать.

Вводные:

- online

- возможно версионность функционала ПО и как следствия разная справка для разных версий ПО. (одни пользователи видят одно другие другое)

- экспорт в pdf

• @ramil6630 Asciidoc+git+antora
• Sphinx doc тоже удовлетворяет требованиям для pdf придётся добавить latex шаблон или взять дефолтный
• Ну и предложу foliant.org, если для маркдауна
• hugo или gatsby + pandoc
• Docsify для Hugo, Docz для Gatsby