Июнь' 2020 в Docops чате

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

💁Участников чата на момент публикации — 688.

Плюсы/минусы Gatsby

MDX

Деплой доки в Docusaurus

Работа с документацией в VSCode

Генерация красивого PDF

Редполитики и стайлгайды для русского языка, линтеры для русского языка

Аналог пулл реквестов в Confluence

Встраивание MD в RST/Sphinx

Ограничения подхода docs as code

Как оповещать об изменениях в документации: нотификации в чате

Связка MD -> Confluence HTML

Упомянутые инструменты: foliant, mdx, docusaurus, gatsby, vscode, xbench, swagger, MyST, GitHub SuperLinter, weeasyprint.

🚧 - вопрос без ответа

🔥- огненная ссылка, must-see

01.06

@SenyaChe отметила минусы Foliant: решила запустить маленький проект на фолианте, захожу пару раз в неделю. при запуске препроцессинга постоянно какие-то грабли: иногда с первого раза всё отлично, иногда часами ищешь что же не так в том же тексте. бестолковые логи, которые пишутся в корень проекта. короче, для меня не взлетело.

• В логи, если включен отладочный режим, пишется много всякого, но конкретные расширения себя идентифицируют, типа flt.preprocessors.includes. Вроде бы, проблемы с препроцессорами можно локализовать достаточно быстро. Но, конечно, нужна тренировка, это я со своей колокольни сужу.

Поднимите ручки, кто использует mdx. Как оно вам? Пора?

Для справки: MDX - это расширенный маркдаун с поддержкой JS компонентов и библиотек: https://mdxjs.com/

Обсуждение плюсов-минусов Gatsby, начиная от https://t.me/docsascode/14873 этого сообщения.

03.06

@exebeeche: а есть у кого нить опыт с докузарус? разворачиваю сейчас доку на этой площадке.делаю пока структуру в джейсоне sidebars, какие то ещё действия надо делать для разворачивания доки? передеплоивать, или он на лету всё делает

• @SuckMyNuts https://github.com/facebook/docusaurus/pull/663 судя по всему на лету
• @jabba_jedi сайдбар не обновится, пока не стопанешь и опять не запустишь. новые страницы появляются и редактировать можно на лету

08.06

@exebeeche у кого нить есть опыт разворачивания демо площадки с REST API (например, есть спека json или уже в html)? чтоб были описаны все методы с примерами запросов и ответов, и чтоб можно было потыкать их

• Swagger
• Со свагером возникла проблема при наличии большого API - свагер стал жутко тормозить.Примерно 700 методов, и примерно 80 моделей

09.06

Репозиторий после вебинара от @Lananovikova по VSCode https://gitlab.com/svetlnovikova/webinar

🔥Здесь и ниже ребята делятся любимыми расширениями в VSCode: https://t.me/docsascode/14990

11.09

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

• Puppeteer
• Там где-то будет пандок и кастомный цсс
• Если б я решал эту задачу, скормить сгенерённый сайт headless браузеру мне бы показалось самым простым решением
• передо мной вставала такая задача, генерить PDF из dosify-проекта, я за несколько вечеров написал программку поверх puppeteer. работает на ура, но в достаточно узких кейсах правда, я программист, а не писатель)
• Я как-то в канал шарил https://weasyprint.org/

Если говорить о рулах для русского языка, безотносительно технологии, на что бы порекомендовали ссылаться, как на первоисточник?

• Мильчин Справочник издателя и автора
• Есть вот такой док, тут много хороших рефов о нормах
• А вообще по каждому отдельному правилу могут быть свои источники истины, можно собрать из разных, Мильчин хорошо для оформления, например, даты, списки, наращения числительных
• Есть ещё редполитики разных изданий http://rdpk.ru/ тоже берёте наиболее понравившуюся и адаптируете
• Хороший стайлгайд у Контура

🔥@ivan_cheban Насчет линтеров для русского языка. Переводчики и редакторы используют очень мощную штуку xBench: https://www.xbench.net/ Там можно создавать свои чеклисты или использовать существующие для проверки на соответствие разным нормам или на ошибки. Это приложение, в которое загружается файл перевода и прогоняется на разные чеклисты

Ссылка на общие чек-листы для русского языка: https://drive.google.com/drive/folders/1Gi98RezYDNj78ZbG18SgumNFMuNg-XJM?usp=sharing

@vldmtr Пытаюсь найти инструмент для удобного управления изменениями в страницах Confluence - по принципу pull request'ов: любой пользователь может форкнуть документ, внести правки и предложить влить их в документ, ответственный товарищ (или группа товарищей) рассматривает предложение и принимает/не принимает. Пока попадается что-то около, но не то (типа Comala Workflows) или просто тикеты на atlassian.com без внятного ответа, где люди описывают что-то подобное.

• А чем workflows не заходят? Там можно как в джире нарисовать разные флоу ревью с триггерами перехода на другой этап. последним этапом можно сделать вливание изменения в прод версию (при это можно просматривать и управлять соответственно отдельно редактируемую, и финальную, и ту что на проде) и даже таски навешивать на каждого ревьюера, похоже на Approval rules в gitlabПросто сделать права на спейс так, что все могут внести изменения, тем самым создав некий условный форк, и отправить на рассмотрение, а ревьюить и вливать - ограниченный круг. А по умолчанию все будут видеть прод версию документа. Минус что форка не может быть два, это ограничение конечно
• плюс, если я не путаю, там история правок из кандидата в релиз не копируется, т.е. все творческие муки и метания останутся незадокументированными - нет полноценной истории коммитов
• @serhit: Azure Wiki-as-a-Code полностью использует концепцию Pull Request.

12.06

@i_tsupko Коллеги, а есть что-то для организации mindmap-ов как код?

• https://t.me/technical_writing/414

🚧А можно еще общефилософского совета спросить? Тот же confluence, внутренняя документация, две команды - "разработка" и "эксплуатация". Документация общая, но пространство и понимание прекрасного у каждой команды свое, документы перебрасываются через стеночку, с "анализом и согласованием". Особую боль вызывает поддержка документов, так как изменения происходят часто, а из инструментов взаимодействия есть только комменты. В результате, почта ответственных за доки заливается сообщениями "ой, у вас тут ус отклеился", причем нагрузка распределяется очень неравномерно: создать запрос на правку легко и это может сделать любой, а вот внести ее несколько сложнее и это делает кто-то один. Возможно ли как-то выправить этот баланс? Где/кого почитать-послушать на эту тему?

16.06

@factorized Твиттером принесло неожиданное: https://myst-parser.readthedocs.io/en/latest/index.html MyST allows you to write Sphinx documentation entirely in markdown.

• @Lananovikova внутри Sphinx есть экстеншн m2r который ровно тоже позволяет, даже в одном и том же документе, я пока не поняла, в чем отличие этого, коме того что писать рст специфик элементы надо как блоки кода. Изучаю - вернусь
• Nick Volynkin: а метаданные в rst тоже есть, только они непопулярны, формат:key: value :key2: value2
• В новой тулзе маркдаун сразу читается в AST, а в старой сначала конвертируется в reStructured Text

17.06

Подскажите, как pandoc на RHEL 7.7 x86_64 поставить? yum install pandoc не катит, потому что это машина в замкнутом сегменте, а в локальном репозитории пакета пандока нет.

• @NickVolynkin: docker pull чтототам/pandoc:latest Выполните команду, чтобы поднять тунель ssh -ND 0.0.0.0:9999 -vvv юзер@машина-с-интернетом Выполните команду в соседней консоли, чтобы установить pandochttpproxy=http://0.0.0.0:9999 yum install pandoc
• B M: Поднимите у себя локально на обычной машине докер контейнер с чистой центосью и ставьте туда pandoc через rpm'ки. Когда осилите, у вас будет сборник всех необходимых rpm.
• iakov v: либо на другой машине RHEL с нормальным интернетом сделать yum install --downloadonly --downloaddir=<directory> pandoc и yum скачает все зависимости, но не будет устанавливать
• и самое главное - это делает плагин для yum, поэтому сначала надо сделать yum install yum-plugin-downloadonly

18.06

🔥@SuckMyNuts https://github.blog/2020-06-18-introducing-github-super-linter-one-linter-to-rule-them-all/

19.06

Том Джонсон разочаровался в подходе docs like code и теперь склоняется к docs like prose: https://idratherbewriting.com/blog/treat-code-like-code-and-prose-like-prose/ Далее идет обсуждение ограничений подхода Docs as code: https://t.me/docsascode/15326

@maxlapshin Коллеги, мне все таки кажется, что концепция docs as code - это вовсе не переход от ворда к hugo, а что-то посерьезнее. Вот как поддерживается целостность и непротиворечивость документации? Какими усилиями поддерживается согласованность продуктового видения и документации?

• да так же как и в коде — то есть руками, да
• Некоторые вещи тестами покрываются, например, отсутствие битых ссылок, отсутствие ошибок от линтера.
• Такое можно реализовать для документации, которая объясняет, как добиться конкретного результата. Для которого все шаги по интерфейсу известны. Можно селениумом или UIPAth проходить и сравнивать результат

🚧Коллеги, кто знаком с Antora, подскажите, есть ли возможность настроить автоматический процесс публикации в Netlify при коммитах в репозиторий в гите? На сайте в документации описана публикация в GitHub Pages. Но сами они свой сайт публикуют в нетлифай. Их netlify.toml не смог настроить под себя.

22.06

как оповещать об изменениях в документации? надо в аттрибутах каждого файла прописывать, кого оповещать при изменениях — и пусть она кидает нотификации в нужный канал с меншном нужных людей/позиций.

• @SuckMyNuts: GitHub actions + slackbot
• да, можно сделать на уровне ci, и выглядит как будто правильно это делать там. А ещё нужно будет кучу нюансов продумать про то, в каких ситуациях что кидать, и как кастомизировать оповещения об обновлениях (релиз-мессаджи этакие) и т.п.
• Это похоже на code owners https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners
• Делаем через gitlab action в слак да, постэкшон после публикационного пайплайна, от имени бота по имени Эрнест (у него Хемингуэй на аватарке))
• Ну и если автор и ревьюеры — люди технические и могут в гит/гитхаб/гитлаб, то первая задача сводится к задаче про изменения в коде. Мне нравится, как это у нас в Плеске сделано: на каждый пуллреквест бот создаёт канал в слаке и приглашает туда автора и ревьюеров. Потом тот же бот в этот чат дублирует все комментарии из ПР. При этом никто лично не меншнится, но в непрочитанных видно новый чат. Как ревьюер я просто смотрю в слак, когда мне удобно, замечаю этот чат и захожу поревьюить. Если ПР совсем срочный — а это бывает крайне редко, если там тесты упали — то мне пишут в личку. А по второй категории, имхо, лучше работает пуш. Просто куда-то публикуем журнал изменений. А сильно технические читатели внутри компании идут смотреть git log.

24.06

@DarthVader ...Было дело, устраивали мы схему с controlled documents, чтобы автоматически ревью и аппрув процессов/процедур/постмортемов/кастомер коммюнике делать. Примерно так это и работало - у каждого документа есть RACI матрица, по которой для I отправлялось уведомление в слак, для R делалась ещё и таска в джире, которую мог закрыть только аппрувер, и так далее

Когда вынесли всю рутину за скобки, то количество выходов за SLA для постмортемов сократилось на 78% https://t.me/docsascode/15439

26.06

Кто может подсказать : planuml диаграммы не отображаются в превью asciidoc. Кто имел с этим дело?

• Не та версия джавы, не та версия PlantUML, не та версия плагина, лежит сервер PlantUML, фаервол банит этот сервер, плохое соединение, да куча всего. Дай воспроизводимый пример.

Коллеги, кто-либо из вас занимался документацией для ДевОпсов, включая описание CI/CD, создания и настройки AWS environment’ов? Если есть возможность, поделитесь, пожалуйста, примерами таких работ/инструкций.

• Имхо, тут работает тот же способ, что и с изучением естественных языков — чтение. Причём активное, по делу, для рабочей задачи. Находишь хоть какую-нибудь задачу, для которой нужен AWS или k8s, своими руками её делаешь и в процессе много читаешь документацию на это всё. А ещё Stackoverflow, тикеты на Гитхабе, примеры кода чьи-то — всё, что каждый день читает обычный разработчик/девопс, для которого ты будешь писать.
• Когда я совсем только вкатывался в девопс, мне документация не очень помогала, зато помогло видео. Видимо, есть часть совсем начинающей аудитории, для которой нужны именно обучающие видео. https://t.me/docops/323

30.06

Кстати про pandoc, раз уж о нём речь. Кому-нибудь попадались какие-нибудь удобные связки из pandoc и клиента к Confluence, которые бы позволяли имеющиеся .md файлы автоматически конвертировать в Confluence XHTML и публиковать в Confluence?

• Foliant называется такая связка ) https://t.me/foliantdocs
• А вроде в двух форматах в Confluence можно PUT делать. Не обязательно в wiki markup. Или тут не об этом?