Lana

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

2020-07-22T16:27:42.004Z

Это краткое резюме дискуссий и полезных ссылок в чате 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. Или тут не об этом?

Май в DocOps чате

2020-07-20T08:12:25.311Z

Это краткое резюме дискуссий и полезных ссылок в чате 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

Апрель в DocOps чате

2020-07-20T07:37:49.903Z

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

Мониторинг сайтов с документацией

Настройка оглавления и переменных в Sphinx

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

Построение майндмэпов из маркдауна

Деплой сайта без кода

Автоматическая съемка и публикация скриншотов

Проверка сломанных ссылок

У Zeit поменялись цены и условия

Упомянутые инструменты: Grafana, Sphinx, markmap-li, Netlify, Zeit, Cypress, Hugo, Jekyll, brok, muffet,

01.04

Что использовать для мониторинга статики с документацией?

Prometheum/Grafana/ELK
@Stanislav_techwriter поделился статьей, как прикрутить мониторинг: https://docs.google.com/document/d/1-erjOtICSP-NGOvY6b1SZec3jV0zvMZNbTQdgSnD_aE/edit?usp=sharing
@maxlapshin предложил прикрутить яндексметрику, она будет сообщать об отвале хостинга.

04.04

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

Не попадались ли кому-нибудь инструменты, позволяющие это реализовать?

В Sphinx в rst_epilog
Попробовал, подстановки типа |variable| не подходят для .. include::, видимо подстановка происходит после того, как Sphinx пытается получить путь до файла

06.04

Подскажите как в sphinx сформировать toctree так, чтобы описание модуля 2 было подпунктом в дереве навигации модуля 1? Если наглядно, то как сделать "Geoserver" подпунктом "Установка дополнительного ПО"?

можно убрать его из общего toc и сделать локальный toc внутри страницы установка дополнительного по на сервере

11.04

Коллеги, кто-то сталкивался с документированием по теме блокчейнов и прочей дребедени?

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

13.04

Ищу заклинателей swagger2marup и asciidoc

Разработчики баловались swagger2markup. Потом пришел новый senior и все перешли на Spring REST Docs и Spring MVC Test. в итоге на выходе я теперь получаю html вместо swagger. И в MkDocs этот html довольно симпатично отображается
@nmpotashnikoff: swagger2markup не поддерживает Open API 3. Мы пользуемся вот этим проектом https://github.com/openapi-contrib/openapi3-generator На выходе имеем asciidoc, причем размеченный тэгами. Т.е. в конечную документацию я могу вставлять не сгенерированные файлы а то из них, что нужно. А дальше — html... pdf... jekyll... все. что душе угодно. Нужны только npm и OpenAPI 3 Generator

14.04

а кто-нибудь встраивал сваггер в статику с md?

@ivan_cheban https://enigma.com/blog/post/integrating-autogenerated-content-into-your-documentation-site-using-swagger-and-jekyll?d=1

17.04

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

как вы это решили?

по факту это не так. Такому менеджеру рядом нужен ещё девелопер, который сбекапит мускль, поправит настройки.
Отвечая на вопрос: у меня сайт правит менеджер сайта (по сути он больше про SEO) и техпис. Оба могут что-то пойти сделать или хотя бы внятно сказать «ой, у нас всё сломалось, помогите».

А Netlify вы не рассматриваете для деплоя? Я уже пробовал GitHub Pages, GitLab Pages. Мне больше всего понравился Netlify. Я ещё не пробовал S3.

@nineteeneyes Есть очень интересное решение от ребят из Zeit. Они же авторы Next.js и остальных толковых вещей. https://zeit.co
Опробовал Zeit. Отличная штука! В несколько тапов с мобильного задеплоил мои эксперименты на Джекилле. Очень быстро билдит, минуту.

18.04

@olegkovalov поделился ссылкой на сервис, который строит майндмапы из маркдауна markmap-lib: https://markmap.js.org/repl/

19.04

А как называется процесс проверки, что перекрёстные ссылки в документации ведут туда, куда надо, и не делают 404?

broken links linter/checker
@factorized: Аккурат сегодня на HN проскакивала маленькая утилитка для этого, https://github.com/smallhadroncollider/brok
@maxlapshin: Я только что ее через ruby gem mechanize сделал, чтобы провалидировать, как ссылки переехали с сайта на сайт
попробовал brok, но он не умеет во внутренние (относительные) ссылки
попробовал muffet, но мне всё таки хочется запускать эту штуку перед деплоем (на папке, а не на сайте), а не только по крону
Попробуйте https://github.com/gjtorikian/html-proofer
Не сталкивались что на некоторые URL-ы 100% валидные выкидывает timeout?Из самых заметных примеров: http://techradar.avito.ru/, другие чекеры вроде его съедают нормально.

21.04

Неожиданно Zeit стал Vercel: https://zeit.co Новости об изменениях в платформе: https://m.youtube.com/watch?v=WaxRMqh_cK0

Поменялись цены и условия.

24.04

@ivan_cheban: Netlify гораздо быстрее, чем Zeit (Vercel) деплоит изменения на статическом сайте в Джекилле. По крайней мере, если комитишь из фористри. 1 минуту — нетлифай, 3 минуты — Vercel.

26.04

@maxlapshin Хотел поделиться: мы в флюссонике начали имплементить такую идею, чтобы склеить тесты и документацию.

В документации полно примеров кода, которые непонятно кто и как проверял. Есть скриншоты и видео, которые делались техписом вручную. Техпис настраивал софт, кликал мышкой, т.е делал ту же работу, которую делает тестировщик. Хочется максимально заменить ручную работу на автоматическую.

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

Реализация: Тест на Cypress, который делает то же самое, что и техпис. Но в нужный момент делает скриншот

как вам идея вообще обойтись без кода, чтобы задеплоить сайт? Вот человек рассказывает и показывает, как это сделать: https://geshan.com.np/blog/2020/04/jamstack-tutorial-website-with-no-code-for-free/#steps

28.04

@ivan_cheban: Нашел интересный сайт со статистикой по разным технологиям, включая SSG: https://www.wappalyzer.com/technologies/static-site-generator

30.04

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

@b0g3r Мы в tlroadmap используем CC-BY 4

Март

2020-04-21T21:09:14.917Z

Участников чата на день публикации: 630 (+37)

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

Документация должна быть ближе к месту ее потребления

Сборка документации из разных репозиториев

Как комментировать срендеренные документы

Генерация документации для фронта

Как инклудить код в sphinx

Делать из скринкастов в Selenium/Cypress документацию

Упомянутые инструменты: gatsby, hugo, antora, foliant, omegat, sphinx, coda, videopuppet, expounder.

01.03

@ArinaBallerina: Когда пытаюсь через 'hugo -D' сложить результат в папочку, дизайн пропадает, то есть на выходе я получаю голый html без стилей и картинок

-D генерит драфтовый вариант сайта. Есть еще ключ -disable fastrender
Также, если вам надо разместить на внешнем ресурсе, вам надо скопировать папку public.

Оказалось, что hugo генерирует ссылки будто ассеты лежат в корне. Вот такие: <link href="/dist/css/file.css" rel="stylesheet">. И на локалке это работает как будто ассеты лежат где-то в корне, а они не там. Когда открываешь html локально с диска, абсолютные пути ведут не туда.
Поэтому для демонстрации нужен hugo serve или любой простой вебсервер.

https://www.jetbrains.com/help/pycharm/documentation-tool-window.html можно заставить сканить внешнюю документацию.

02.03

@b0g3r: что сейчас есть красивого для статических сайтов? Для митапа хотим собрать простенький лендинг и немножко документации.

Gatsby. Hugo. Antora.

Если кому надо что-нибудь подеплоить некоммерческого или коммерческого или небольшого — мы тут обнаружили волшебный https://kintohub.com, который умеет и в серверлесс, и в веб-приложения, и в сборку, и в статику.

Несколько dev-команд работает над программным продуктом.
Репозиториев у нас сотни, ибо продукт большой.
Репозитории лежат на GitLab (self-hosted) и на Github.
Технические документы пишутся на markdown и лежат в репах так же, как код. Документы по конкретному сервису лежат именно в его репе.

Хочется:
сделать сайт, на котором централизованно можно почитать всю эту нашу документацию из репозиториев. И чтобы был глобальный поиск по ней.
Есть ли для этого какой-то готовый инструмент?

@b_shchuko Хочется: сделать сайт, на котором централизованно можно почитать всю эту нашу документацию из репозиториев. И чтобы был глобальный поиск по ней.
Есть ли для этого какой-то готовый инструмент?

Берите почти любой ssg из ссылки выше (staticgen.com), просто отсортировать те, что исходником умеют md: Jekyll, gatsby, Hugo, mkdocs, foliant, docusaurus. Gatsby вроде умеет в несколько репозиториев, там есть source-git, но я не тестировала

Или публикуйте отдельными приложениями с одинаковой версткой и сделайте им схожие URL через cname. docs.site.com/api, docs.site.com/guides, docs.site.com/db и т.п. docs.site.com будет разводящей со ссылками на остальные доки. поиск можно через Algolia например настроить, но нужно смотреть, как будет работать с разными приложениями.

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

foliant.org умеет.

06.03

@shrimpsizemoose: А есть ли сервисы где можно оставлять комментарии к срендерным md/rst/whatever документам?

Foliant (https://foliant-docs.github.io/docs/) умеет выгружать из md-исходников в Confluence с более или менее сохранением инлайн-комментариев. Если место, которое было закомментировано, изменилось в новой версии документа, коммент сохранится (но как правило растянется на весь абзац, потому что точное место уже не определить).

есть платный плагин к конфе, который вытягивает мд. Далее этот мд можно засунуть в гит и через питон скрипт настроить автоматический чек и пуш.

наверное, можно написать какой-нибудь полуавтоматический конвертер-аплоадер docx в Google Docs.

@ayemelianov: кто-нибудь в чате собирал с его помощью документы на языках с иероглифической письменностью? китайский, японский?

Да, https://www.helpandmanual.com/help/hm_advanced_tools_spellchecker_usecustom.html?q=dictionaries

@SenyaChe: Всем привет! Подскажите, есть ли готовая тулза(скриптик), которая собирает единый документ из разных репозиториев?

Foliant, https://github.com/jamesramsay/hercule.

11.03

Всем привет! Кто-нибудь использует инструменты для "схем как код"? Какие сейчас на волне? Что посоветуете посмотреть?

Mermaid.js, PlantUML. Для микросервисов лучше diagrams by mingrammer
https://diagrams.mingrammer.com/docs/getting-started/examples.

https://github.com/RicardoNiepel/C4-PlantUML

12.03 🎂 Ник, с днем рождения!

13.03

Раз уж пошла тема про swagger - у кого нибудь получилось корректно использовать параметр confUrl при настройкe swagger-ui?
https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

19.03

@maxlapshin: Коллеги, насколько пригоден современный синтез голоса для видеоскринкастов?

Год назад я для забавы тестил Amazon Polly, и для английского она была вообще огонь

Я сейчас прорабатываю с тестировщиком и техписом вопрос того, чтобы сделать документацию тестируемой. Т.е. скринкаст — из селениума/cypress. Оттуда же скриншоты. Сделать в таком режиме озвучку не роботизированную означает откладывать каждый раз на недели её релиз. Пример: https://flussonic.com/doc/installation#password

@Firniar: подскажите, в markdown можно стили свои добавлять?

MD просматривается в текстовом виде. Стиль можно определить в настройках текстового редактора. Выходной формат, например, в html производится конвертором, к которому можно подсунуть css.

24.03

https://skorokithakis.github.io/expounder/ - интересная реализация того, как можно разделять общую и дополнительную информацию (в an example можно посмотреть детальнее как это работает).

25.03

Статья про то, почему не нужно использовать маркдаун для документации: https://buttondown.email/hillelwayne/archive/please-dont-write-your-documentation-in-markdown/

На HackerNews вчера такой хайп был. Аж три статьи на эту тему. https://news.ycombinator.com/item?id=22675165
Чтобы не перечитывать 100500 комментариев краткие выводы:
1. Документация должна быть. Если кто-то не хочет писать из-за инструмента, то пускай уж использует что хочет
Пруф https://news.ycombinator.com/item?id=22678848
2. Маркдаун победил. Так как он достаточно хорош по сравнению с plaintext.
Пруф https://news.ycombinator.com/item?id=22681972
3. все кто просветлился, советуют asciidoc и rst. Приводят доводы, но их не слышат.

@SenyaChe: Привет всем! Каким терминалом пользуетесь под виндой (кроме bash и powershell)?

пробовали https://www.microsoft.com/en-us/p/windows-terminal-preview/9n0dx20hk701?activetab=pivot:overviewtab.

27.03

@serembon: у нас небольшой проект, фронт на реакте, бэк на питоне. Для документирования бэка мы используем sphinx, он покрывает все наши потребности.
Сейчас мы задумались как генерировать документацию для фронта, какой инструмент использовать?

Для документации по UI Kit'у лучше сразу Storybook взять, он под это заточен.

Andrei Yemelianov: вопрос ко всем, кто работает на связке pandoc+markdown.
как вы поддерживаете многоязычность?

если речь про перевод документов, то есть плагин к OmegaT, который поддерживает markdown. я переводил с помощью этого плагина md-файлы «обычной» сложности, без таблиц и сложных списков, вроде бы всё работало as expected.

29.03

👍Markdown2video https://www.videopuppet.com/docs/script/

30.03

@exebeeche: Кто работает со связкой sphinx&rst, есть ли возможность использовать так называемые сниппеты кода?

да, есть, я так куски кода инклудила прямо из файлов с кодом, можно указать с какой по какую строку инклудить.

.. include:: имя файлика literal: start-line : integer end-line : integer

там еще куча модифайеров есть https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment.

@ayemelianov: Существуют для плагины для MemoQ, которые поддерживают Markdown?

Вроде, писали выше про Okapi как конвертер из XLIFF в маркдаун. пишут, что файлы .md можно затащить в мемокью, поменяв в фильтрах расширение на Plain Text Filter. https://forum.door43.org/t/markdown-memoq/127

31.03

@zupchik: Для внутреннего пользования нужна документация одного конкретного проекта.
- Цели: упрощение входа нового сотрудника; представление всех компонент, способов и мест их развертки (облако, кастомные пользовательские устройства, смартфоны, тестовые платформы);
- Ресурсы: один человек (я), крайне малое количество времени.

https://www.notion.so/. https://coda.io/

Поднимаете виртуалку, туда пихаете nginx на нем поднимаете вебсервер и через hugo+ markdown генерите вебпортал.

Подскажите, плз, гайд или еще что-то, что поможет понять, КАК писать

https://developers.google.com/tech-writing/one/words можете взглянуть на гайд от гугла.

есть очень приятное и короткое введение Modern technical writing: http://a.co/fI895I3

Февраль' 2020 в Docops чате

2020-04-19T20:56:31.526Z

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

asciidoc

Сборка образа с документацией и настройка CI

Переход с help&manual на ssg

Мониторинг сайтов с документацией

Документирование структуры компьютерных сетей

Миграция документации из Confluence

Упомянутые инструменты: hugo, antora, swagger, help&manual, Racktables, iTOP, sunbird dcim, pandoc, doorstop, nots.io.

04.02

@ramil6630 спросил Коллеги, кто пробовал antora и Hugo. Что выбрать для работы с документацией? Планируем asciidoc в качестве формата.

антора для аскидока. Для Hugo тоже есть поддержка asciidoc, при этом он на go. Тему можно использовать: https://docsy.dev/

постоянно, при правках, надо удалять public
импортирование новых shortcodes еще та задача
многие js-файлы написаны без соблюдения стандартов разметки

---------

не нужно, нужно ребилдить командой hugo. Там инкрементальная сборка. Если очень хочешь зачищать каждый раз, напиши makefile. Но вообще в процессе работы это не нужно. И обрати внимание на hugo serve, это очень удобно.
положить файлы в папку
код трогать не надо там

Как сделать поддержку версионности на Hugo? Первая мысль: Класть в соседние папочки версии и в хэдере вместо языков тулить версии. Получается отдельный сайт для каждой версии.

06.02

Если ты делаешь документацию, то тебе нужно только собрать образ. Надо написать Dockerfile (это простой скрипт) и сделать:

docker build -t registry.mycompany.com:443/group/project/docs
docker login registry.mycompany.com:443
docker push registry.mycompany.com:443/group/project/docs

Можно в этом executor не собирать внутри образ как в матрёшке, а прям уже нужный образ на нём запустить. тогда и логи информативнее станут, и возможно будет понятно, где ломается и почему доки не обновляются.

Есть заготовки документации на разных инструментах с заранее настроенной сборкой и публикацией на GitLab Pages. Отличная песочница, чтобы попробовать разработку документации как кода. https://gitlab.com/pages/

09.02

@ayemelianov Коллеги! А есть у кого-то опыт перевода с одного инструмента публикации -на другой? Мне сейчас надо реализовать переезд с Help and Manual - на что-то менее глючное и более простое.

Да, переводил с AuthorIT, с локализацией на Sphinx, reStructuredText. В целом идея такая: найти промежуточный формат F, чтобы оптимально конвертировать HM -> F -> язык разметки. У нас это был HTML, но мог бы быть и XML какой-нибудь или даже DOCX.

10.02

Сложно, проприетарно, глючно. Ещё по нашему опыту с аналогичным AuthorIT: долгая сборка и публикация, много ручных действий, риски всё протерять, изолирует техписателей и не допускает других людей к работе над доками, нет инструмента для ревью. Какие-то свои форматы файлов, которые сложно редактировать, не имея H&M под рукой + очень сложная процедура сборки, часто вылезают непонятные ошибки + часто собирает очень долго, даже слишком долго + сложно с чем-то интегрировать.

Как конвертировать картинки? pandoc (https://pandoc.org/) умеет конвертировать DOCX в reST, Markdown или AsciiDoc вместе с изображениями:

pandoc -f docx --extract-media images -t rst -o document.rst document.docx pandoc -f docx --extract-media images -t markdown -o document.md document.docx pandoc -f docx --extract-media images -t asciidoc -o document.adoc document.docx

Изображения будут в директории images. В любой разметке сразу будут правильные ссылки на них.

11.02

@Elaneor: Хотелось бы спросить у тех, кто работает с mardown, как вы организуете хранение файлов, как можно, например, "хотя бы оценить объем текста", как отслеживаете изменения этого текста (например, если документы и их изменения для следующих версий планируется отдавать на перевод)?

Пока что могу предложить свой старый доклад на SECR. Там я рассказывал в целом о преимуществах подхода «документация как код», в том числе было про хранение файлов, ревью, переводы и публикацию. https://youtu.be/sVStWzgDnNA

👍Конспект митапа, "Что делать, чтобы документация не болела?" http://docops-hq.github.io/conf/teamleadconf/20/documentation_challenges/

12.02

Всем привет. У нас в компании возник интерес к подходу «документация как код». Подскажите источники, с которых можно начать изучение данной темы, чтобы еще больше себя не запутать

https://starkovden.github.io/Switching-tools.html и https://www.youtube.com/watch?v=6W20lMycgIY&list=PL8i3cg9-YErMG1ZrMNDGUjTQe-p4tRgY3

@DarthVader: Попробовал https://diagrams.mingrammer.com/docs/node Резюме: (+) писать легко
(+) питон
(+) *aC подход в полный рост.
(-) невозможность делать двунаправленные связи
(-) невозможно показать тип связи или больше одного их типа
(-) под капотом graphviz, поэтому на автомате выходит уродливое нечто, особенно если в диаграмме больше полудюжины элементов и связи не 1:1
(-) если нужно быстро сгенерировать диаграмму, с таким же удобством и эстетическими свойствами пойдет и PUML.
@baharev_np: Мигрируем документацию из Confluence в Hugo. а каком этапе надо выпиливать все лишние атрибуты из текста и как вообще привести его в удобоваримый для хьюго вид?

На этапе HTML его надо попарсить и вычистить. Я использовал Python и BeautifulSoup.

вот взгляните на примеры в разделе converting content https://developer.atlassian.com/server/confluence/confluence-rest-api-examples/

У самого такая задача есть (у меня даже выгрузки в html нет из конфы)
есть еще https://www.npmjs.com/package/confluence-to-github-markdown

14.02

@mrxcrr: Кто-нибудь где-нибудь встречал удобный для ежедневного использования формат для описания/документирования активно меняющейся компьютерной сети, со всеми значимыми узлами (рабочие станции, сервера, виртуальные машины, маршрутизаторы), но чтобы с информацией о ролях таких узлов, их состоянии, заметками об установленном ПО и т.д.

https://habr.com/ru/post/444410/

https://www.open-audit.org/

Умеет всякое, в том числе и экспорт-импорт
https://community.opmantek.com/pages/viewpage.action?pageId=26640404

Racktables или iTOP с соответствующими плагинами. Если платно, то есть недорогие инструменты от sunbird (dcim). Очень крутые. Ну из этого класса было ещё glpi. Не знаю, как оно сейчас.

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

17.02

@apoint: Я Александр. Делаю проект nots.io Мы даём возможность прикреплять документацию к коду (просто текст, маркдаун, картиночки, pdf-ки и даже файлы с гуглодиска). Привязать можно к функции, файлу, коммиту или бранче.

Мне очень нравится индекс актуальности на каждом методе и очень не нравится, что доки хранятся отдельно от кода. Хочу чтобы тулза работала как анализатор (по типу code coverage) и, может быть, как CMS над гитхабом, но доки чтобы остались в файлах с кодом.

Анализ того, что код соответствует стандартам (например, о покрытии документацией), это работа lint'ера кода, например, https://checkstyle.sourceforge.io/writingjavadocchecks.html и https://eslint.org/docs/rules/require-jsdoc.

👍Системные требования как код - Инструмент Doorstop. Каждое требование - отдельный файл в формате YAML, есть интеграция с Python. Требования для самого инструмента описаны в виде требований doorstop - https://github.com/doorstop-dev/doorstop/tree/develop/reqs

Презентация - https://speakerdeck.com/jacebrowning/doorstop-requirements-management-using-python-and-version-control

@ramil6630: Кто-нибудь может мне объяснить, почему при всей крутизне asciidoc and rst, никто их не выбирает?

Высокий порог входа. Экосистема инструментария вокруг md шире, и расширяется она тоже быстрее. Ещё у reST ужасная, старперская, насквозь академическая документация. Они называют ссылки hyperlink targets. Вы видели вообще живых людей, которые бы так называли ссылки?

Посчитать, сколько часов разработчика и тестировщика, а также проджекта можно сэкономить (ориентировочно).

Хипстерский, пожалуй, Gatsby, но начинать новые проекты я хочу как и раньше на Sphinx, потому что он всё равно лучше для моих задач. некоторое сравнение есть на сайте https://staticschool.com/.

А есть готовые решения по генерации доки (md например) из JS-тестов? Cypress, Jest, например. Для тестов есть кастомные репортеры, но это отчёт о прогоне тестов, а не документация. Можно написать трансформер для ssg.

Помнится, был фурор про gostdown - набор инструментов для конвертации маркдаун в документы, оформленные по ГОСТу. Лично мне это показалось набором костылей, а задействовать виндовый ворд - вообще ставило крест на автоматической сборке через CI. Так вот, обнаружил на мой взгляд самый идеологически правильный инструмент. https://bitbucket.org/Lab50/espd-docbook5/src/master/

22.02

Интересно, а как посчитать, сколько техпис зарабатывает фирме?

Можно начать с того, что собрать данные — если человек занимается написание материалов для пользователей и для разработчиков, ну те же onboarding guides — от ребят из поддержки и от вновь прибывших/прибывающих разработчиков (то есть попытаться сравнить сколько у них времени уходит на разобраться самому и прочесть уже существующие материалы от Тех Писателя и при этом меньше дёргать старших ребят.

Дальше всё зависит от “политики партии”: некоторые считают, что раз уже всё написано, сделано и поставлено на рельсы, то можно избавиться от человека и сэкономить фонд зп.

@SenyaChe Подскажите, какой мониторинг используете для онлайн хелпов? Хочу отслеживать ошибки фронта + серверные

Разбирать логи nginx, который раздаёт статику. С этим лучше всего прийти к опсам и спросить, что они уже используют для мониторинга других сервисов. Там будет какой-нибудь ELK stack или похожее. Вам отдадут панельку с графиками: количество запросов вообще, сколько 301/302 (надо обновить ссылку), сколько 404 (надо срочно обновить ссылку) и т.п.
Если вы используете CDN, то задача несколько меняется — или у него есть своя панель аналитики, или надо доставать логи.

Внешний мониторинг, который регулярно проверяет доступность сайта из разных точек мира. Например, site24x7.com.

Есть ошибки фронта, которые обнаруживаются не мониторингом, а линтерами и автотестами:

валидность HTML, CSS, JS
доступность (accessibility): картинки подписаны, навигация размечена, текст достаточно контрастный и крупный
скорость загрузки страниц; время до момента, когда пользователь что-то может прочитать
работа редиректов.

Доклад про инфраструктуру фронтенда: https://www.youtube.com/watch?v=yWPAW59e1AU

25.02

@exebeeche: а бывало у кого нить, чтобы пандок криво перебрасывал из md в rst?

У него есть свои особенности и он не все директивы reST знает. Например, не знает те, которые добавляет Sphinx.

26.02

Вопрос ко всем: а есть ли какие-то инструменты, чтобы преобразовать XML, который используется в Help and Manual, в markdown?

Из hm можно сразу делать html. Разработчики hm обещают конвертацию в MD в будущих версиях http://helpman.it-authoring.com/viewtopic.php?t=15517

Январь' 2020 в Docops чате

2020-02-16T18:58:14.511Z

Участников чата на день публикации: 593 (+35)

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

Публикация из Markdown в Confluence

Accessibility

Конвертация HTML в сложный PDF

Генерация PDF pandoc-ом

Мокапы как код

Линтеры и спеллчекеры: лучшие практики, что проверять

Gatsby

Хранение больших файлов

Инструменты для документирования RESTful API

Упомянутые инструменты: gatsby, puppeteer, gostdown, docbook-xsl, pdfunite, cpdf, optima, werf, ghost, redoc, widdershins, phpdoc, md2conf.

1.01

@gr_buza С чего начать писать документацию? С плана. В сети есть готовые шаблоны Documentation plan. C целеполагания технического документа (зачем документ, какая задача бизнеса, задача читателя). Полезный материал: записи лекций С. Факторовича на Youtube: https://www.youtube.com/watch?v=KGVeeKhio70

2.01

Как заставить коллег сначала искать в доках, а потом задавать вопросы? 1. Ссылаться на документ. 2. Надеемся на естественную интраверсию у многих разработчиков. И общую культуру "не отрывай другого от дела без необходимости". Все идет от общей культуры задавания вопросов.

5.01

@zaggaz предложил составить картину мира форматов, инструментов написания, сборки, публикации документации, которые есть у участников чата. Участники несколько дней накидывали свой "стек", вот ссылка на исходный пост: https://t.me/docsascode/12176, а вот ссылка на итоговый результат: https://t.me/docsascode/12695.
https://www.questionpro.com/t/PGhS9ZgCFE Ссылка на постоянно пополняемые результаты опроса тома джонсона для тех, кто пишет девелоперскую документацию. Поучаствовать можно по ссылке: https://www.questionpro.com/t/AOaGwZgCFE.

7.01

Pavel: Можете скинуть ссылки /описать как этот подход docs as code интегрируется в SDLC (Software Development Lifecycle )? 1. Использовать только для клиент-ориентированной документации, а для vision, требования, отчёты об исследованиях, описание решений, RCA — используем Конфлюенс. У него есть интеграция с Джирой, управление доступом, комментарии и другие фичи, оптимальные для этих жанров. 2. Оптимально интегрируется, так как помогает обеспечить прослеживаемость требований к коду, тестам, докам, уязвимостям.

9.01

@Nick_Volynkin Коллеги, кто-нибудь делал пайплайн из Md в Confluence? 1. Foliant умеет https://foliant-docs.github.io/docs/backends/confluence/#confluence-backend-for-foliant 2. Есть Ruby gem md2conf, например. Можно написать Rake task, который вызывать из gitlab ci.
gostdown - инструмент для выгрузки из исходника в docx по ГОСТ. https://gitlab.iaaras.ru/iaaras/gostdown
Accessibility документации: MS сделали контрастную тему, но голосовые читалки не смогут читать документацию из-за отсутствия навигации.

10.01

@AbashkinIvan Ребят, подскажите, кто-нибудь пробовал генерировать pdf через такую связку?
ASCIIDOC -> HTML+CSS -> PDF. На выходе хотим получать красивый PDF https://t.me/docsascode/12279 1. Можно запрограммировать сколь угодно сложную трансформацию (хотя напрямую XSL может превращать только в другие XML-based форматы, то есть в условный HTML), а у latex цель немного другая, поэтому сделать точное позиционирование там можно, но для этого надо проделать очень большую работу. Есть ещё инструмент https://github.com/asciidoctor/asciidoctor-fopub 2. в данном случае docbook-xsl — это нативная для asciidoc вещь и она дает полный контроль над layout'ом в xsl-fo. Другой вопрос, а нужен ли тут вообще docbook-xsl, в листовке нет ни таблиц, ни других сложных элементов, процессингом которых можно было бы воспользоваться. Можно же это все перегнать в docbook и написать свое преобразование в xsl-fo с нуля. 3. Мы генерили PDF из HTML с помощью Puppeteer, полет нормальный. Что видишь в хроме, то и получаешь в PDF, с точностью до пикселя. Плюс можно задавать кастомные размеры для итогового PDF.

11.01

Как склеить вместе два PDF? 1. pdfunite 2. cpdf. Возможно, с pdfunite не разобрался, но у меня при добавлении титульной страницы все ссылки ехали на одну страницу.

14.01

@Stanislav_techwriter [!NOTE] в md никак визуально не выделяется? 1. В дефолтном нет, Юзай > 2. В Hugo есть shortcodes, разбирайся;
Есть неплохой редактор для md-файлов - Optima. У него есть преимущество: нативная поддержка Главреда. Ссылка: https://getoptima.ru/
в vs code можно как-то забиндить или внести в снипеты? Да: https://code.visualstudio.com/docs/editor/userdefinedsnippets

15.01

@lejbron Может кто-то сталкивался - необходимо построить карту внутренней сети с описанием топологии? 1. https://habr.com/ru/post/444410/
@factorized мы тут в поисках линтера для автоматизированной проверки Markdown и RST 1. брать vale и ничего сверх этого не искать.
@Lananovikova собрала все известные мне способы публикации из разметки в конфлуэнс в статейку, https://habr.com/ru/post/483898/ это чуть больше, чем я рассказывала на митапчике, так как sphinxcontribbuilder обновился 3 января и стал поддерживать много классных плюшек, типа джира фильтров, мат формул, нумерованных заголовков и т.д.
@maxlapshin Техпис пишет документацию на сайте, кое где проставляет теги, размечая определенную документацию. Фронтендер пишет вебморду и кое где ставит контрол (в виде знака вопроса) с нужным тегом. При компиляции это все собирается вместе и продукт уезжает кастомерам с документацией, которая свежезабралась с сайта на момент релиза софта.
Обсуждали вовлечение не-девелоперских команд в git и другие дев тулзы, https://t.me/docsascode/12404

16.01

@b0g3r Я с немного грустной, но все таки задачей: меня попросили законсервировать рабочий проект. Покрыть документацией, обновить библиотеки, спрятать это в такое место, из которого потом будет легко найти. 1. я бы начал с того апи, которое выставляется наружу. 2. Я бы быстро пробежался по выжившим участникам и сделал с ними интервью про самое сложное, подлое и неприятное в их опыте с проектом, и что они могут по этому поводу рассказать (причины, решения и тп). Из чек-листа можно предложить только инструкции "как собрать", "как запустить" и "как использовать". 3. сваггер/джавадоки/подобное собрать. код должен быть хорошо задокументирован 4. Попробуй "надеть эту шляпу" и подумать с позиции другого ТЛ, который придется расконсервировать 5. нарисовать максимально высокоуровневую, но полную карту модулей/компонентов и написать к ней текстовый пересказ. Из каких модулей состоит система, каковы ключевые точки и принципы внутрисистемного взаимодействия, и пр. Очень полезно задаться вопросом «почему система задизайнена так» (вместо «как именно задизайнена система»). Во-первых, ответ на вопрос «почему» никогда невозможно извлечь из кода, во-вторых, этот вопрос часто важен для дальнейшей поддержки, а в-третьих, вопрос, поставленный так, очень хорошо снимает writer's block.
Статья на Хабре от Флант про сборка и деплой Docker-образов с werf на примере сайта версионированной документации: https://habr.com/ru/company/flant/blog/478690/ Автор @KladovArtem

18.01

@Nick_Volynkin На хакатоне Профунктора сделали прототип инструмента для описания мокапов интерфейса текстом. Инструмент так сделан, что мы его потом легко в виде плагина к разному софту упакуем. Можно будет, например, в JIRA задачу дизайнеру поставить, накидав ему черновик. Результат: https://imagineui.github.io

20.01

@ayemelianov при генерации PDF pandoc заголовки четвёртого уровня (именно четвёртого) не отображаются корректно, не перед параграфом, а после. Ответ: @iakov v, PDF пандок вроде бы генерирует через промежуточный latex, можно его подебажить. И есть ещё параметр у него, до какого уровня заголовки должны попадать в ToC. по умолчанию там вроде бы как раз 3 уровень, попробуйте увеличить до 4 2. добавляем в преамбулу:

\let\originalparagraph\paragraph \let\originalsubparagraph\subparagraph

\renewcommand{\paragraph}[1]% {\originalparagraph{#1}\hfill} \renewcommand{\subparagraph}[1]% {\originalsubparagraph{#1}\hfill}

@ayemelianov при конверсии в PDF у меня не работает опция пандока toc-depth. 1. https://t.me/docsascode/12551 2. обновиться до последней версии.

22.01

Коллеги, а подскажите примеров документации, где много версий и много языков? 1. https://www.ibm.com/support/knowledgecenter/en/SSEPGG_10.5.0/com.ibm.db2.luw.kc.doc/welcome.html 2. https://docs.unity3d.com/540/Documentation/Manual/

24.01

@ayemelianov может кто дать совет по поводу размеров блоков кода в pdf, сгенерированном средствами pandoc? как зафиксировать ширину? 1. https://stackoverflow.com/questions/20788464/pandoc-doesnt-text-wrap-code-blocks-when-converting-to-pdf
@Lananovikova какие самые лучшие hugo-темы для документации под разные кейсы? 1. @SuckMyNuts Docsy Гугловая тема, понравилась оч, простая, кастомайзебильная, можно прямо из нее попасть в репу и редачить в гитхабе. ок поиск lunr или algolia. 2. Techdoc.
@factorized какие именно ошибки вы выявляете линтерами? 1. Стиль время weasel words, пассивный залог, they them, master slave и прочее гендерно нейтральное всячество 2. На слово "will" ругается, что не надо использовать будущее время в доке 3. Title case. Чтоб заголовки были единообразны 4. мне в первую очередь придумались:
- пунктуация в списках (как в русском, так и в английском)
- капитализация заголовков в английском (sentence style или newspaper style, у кого что принято)
- капитализация аббревиатур
- проблемы с вайтспейсом (лишние пробелы в конце, отсутствие пробела после пунктуации и пр.) 5. антропоморфизм 6. Проблемы с вайтспейсом маркдауновский линтер находит. Ещё у нас есть правило не называть текст ссылок типа кликни сюда 7. Мне очень импонирует проверка сложности предложения, одна из любимых проверок 8. кавычки 9. для русского мы ковырялись с https://github.com/hcodes/yaspeller, выглядит хорошо 10. Лексические иллюзии, начало предложения с So или Итак, и куча-куча клише, которые мы юзаем, а-ля silver bullet, bite the dust и прочие красиво звучащие но не несущие смысла особого выражения
@nmpotashnikoff для любителей asciidoc, наконец произошло счастье: https://github.com/asciidoctor/asciidoctor/pull/3539 и https://github.com/asciidoctor/asciidoctor/pull/3532 Поддержка нескольких хедер-строк в таблицах.
@serhit Коллеги, а кто-нибудь работает в связке MD под гитом с публикацией на SharePoint? 1. Я публикую в SharePoint из MadCap Flare. При публикации с гита забираются автоматически последние изменения. Формат HTML5, но в SharePoint конвертируется в ASPX.
@ramil_rem Коллеги, а кто как хранит и синхронизирует бинарные файлы? 1. Git LFS звучит как подходящее решение. 2. NextCloud.

27.01

@glu0n Хотим сделать базу знаний: установка в частном облаке, устойчивость к нагрузке, удобное редактирование, открытая система, Active Directory, хорошая аналитика посещаемости. 1. После долгих рисёрчей, пришел к выводу, что самое топовое, что сейчас можно сделать, что удовлетворяет всем требованиями — Gatsby (открытый, стойкий, в зависимости от вашего железа, разворачивайте где хотите) 2. есть https://docusaurus.io/en/ на реакте с платным или кастомным поиском, md
А что там с поиском? Sphinx? Lucene у Confluence. Вроде. Нам не очень. Или у них реализация не очень. А может ElasticSearch? 1. если сайт закрытый, то самим пилить fuse.js/lunar.js 2. Для поиска можно использовать те же https://sphinxsearch.com, https://lucene.apache.org + немного фронтового колдунства
@SuckMyNuts поделился ссылкой на репозиторий с упрощенным клоном Jira https://github.com/oldboyxx/jira_clone
@filhodejaneiro В сегодняшней рассылке LeanPub увидел книгу про ReportLab - средство генерации PDF из Python. Может быть кому-нибудь тут будет интересно, по ссылке можно купить со скидкой https://leanpub.com/reportlab/c/LeanpubMonthlySale2020Jan27

28.01

@jabba_jedi поделился ссылкой на платформу для организации работы https://fibery.io/anxiety
Возникла идея попросить у хабра создать хаб про docops/docs as code.
@baharev_np Коллеги, помогите советом: есть большой документ в конфе, цель - сделать рядом с оглавлением поле для поиска. Сложность в том, что нужно ограничить область поиска одним документом. Как это сделать? 1. Вынести в отдельный спейс, тогда поиск будет по умолчанию только по этому спейсу. 2. Спросить в https://t.me/atlassian_community или @augmoscow
Есть какой-нибудь имадж для сборки хуго, в котором есть postcss? попробовала hugo_extended ругается, что нет postcss 1. https://hub.docker.com/r/klakegg/hugo

29.01

@shakhbazyan Есть продукт, у продукта есть API. Документация у продукта в Confluence, включая документацию API.
Есть мысли автоматизировать документирование API следующим образом:
1. Разработчик API в процессе пишет комменты в коде неким согласованным образом, по какому-то шаблону;
2. Дальше мы собираем эти комменты, скармливаем их какому-нибудь условному phpdoc (первое, что пришло в голову, скорее всего, есть варианты лучше);
3. Из скормленной ранее документации формируется HTML и постится в заданный раздел в Confluence. 1. для RESTful надо брать OpenAPI, т.к. вокруг него самая богатая экосистема инструментария https://t.me/docsascode/12919 2. у нас redoc в связке со сфинксом билдит очень приличную html-ку из спеки OpenAPI в yml формате 3. Еще есть путь: https://openapi-generator.tech/docs/generators 4. нам очень зашел widdershins: конвертер из OpenAPI в md https://github.com/Mermade/widdershins
@unchase поделился репозиторием со списком полезных русскоязычных ресурсов, связанных с ИТ https://github.com/unchase/awesome-russian-it

Декабрь'19 в Docops чате

2020-01-05T12:43:32.398Z

Участников чата на день публикации: 558

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

выбор SSG

фильтры pandoc

сбор фидбека к документации (CSAT)

метатеги в Markdown

генерация документации в PDF при использовании MkDocs

сравнение двух текстовых pdf-файлов

Docusaurus 2

1.12

Что обсуждали: выбор SSG

@murgut спросил, существует ли либа, которая будет соответствовать этим требованиям: подсветка кода, вывод документа единым списком, подсветка аннотаций, встраивание движка для интерактивных примеров, мобильная версия, поддержка <head> тегов, пререндер html.
@NickVolynkin ответил, что подсветка синтаксиса обычно реализовывается отдельными библиотеками (pygments, rouge, т.д.), пререндер html есть почти везде, теги в head также почти везде, где можно редактировать шаблон, мобильная версия зависит от темы. В остальном, лучше выбрать что-то из http://staticgen.com лучше на JS, если это ваш основной язык. @DarthVader добавил, что есть еще highlight.js.
Сайт reactjs сделан на движке Gatsby https://github.com/reactjs/reactjs.org#running-locally.

10.12

@ligurio порекомендовал тьюториал по написанию документации для Unix - https://manpages.bsd.lv/mdoc.html
@ArinaBallerina поделилась, как решала проблему генерации документации в PDF при использовании MkDocs, пробовала md2pdf, typora, foliant, голый pandoc. Ссылка на сообщение и последующий тред: https://t.me/docsascode/11631

12.12

У Gatsby есть стартер паки для быстрого поднятия под разные нужды, вот например для блога: там всё сводится к gatsby new gatsby-starter-blog https://github.com/gatsbyjs/gatsby-starter-blog

16.12

Обсуждали, кто как делал фидбек для документации. Варианты: можно использовать events в Google Analytics, подключить сторонний макрос, использовать typeform, создавать ишью в репозитории или Джире. @filhodejaneiro поделился ссылкой на туториал для SSG+GA https://www.docsy.dev/docs/adding-content/feedback/ Пример из Plesk: https://docs.plesk.com/en-US/obsidian/administrator-guide/about-plesk.70559/
@SirEdvin поделился ссылкой на release notes https://vector.dev/releases/0.6.0/, сделанные на Docusaurus 2 (https://github.com/timberio/vector/tree/master/website). Темная тема включается при соответствующей настройке в системе. параметр prefers-color-scheme. Ссылка на релиз новой версии Docusaurus: https://deploy-preview-2100--docusaurus-2.netlify.com

18.12

Что обсуждали: фильтры для pandoc, работа с linux под windows, как анализировать фидбек на документацию.

Ссылка на доклад Андрея Емельянова на мини-гипербатоне про lua-фильтры для pandoc: https://www.youtube.com/watch?v=LjB7C24EO5c
Команды переброса из rst формата в md для pandoc: https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd
В бету вышла Windows Subsystem for Linux 2: https://devblogs.microsoft.com/commandline/wsl-2-is-now-available-in-windows-insiders/
Вопрос: есть легаси-документация в docbook xml, перегнал в md, теперь хочу в PDF. Ломаются сложные вложенные списки.
Как анализировать фидбек? Среднее время чтения, лайки vs дизлайки, хитмапы. Отсортировать статьи по среднему баллу, улучшать самые плохие.

20.12

@oplatonova задала вопрос про Markdown, можно ли в исходном файле md (который будет конвертирован в html) ввести дополнительные теги - например, указывать ключевые слова, которые будут конвертированы в вид <META Name="keywords" Content="keywor1, keyword2">. Ответы: https://www.markdownguide.org/extended-syntax/#definition-lists && or https://www.markdownguide.org/extended-syntax/#footnotes
pandoc может из YAML metadata block. Это не чистый markdown, конечно, но и не HTML внутри markdown, с помощью такого ключа можно добавить параметры title и keywords, которые экспортируются в HTML-документ, или записать тоже самое в YAML metadata block.
Можно ли в исходном файле tex. при конвертации в docx исключить из вывода некоторые блоки? Например, из блока \begin{ figure} и begin{tcolorbox} вывести figure. Можно написать фильтр (pandoc lua filters).

24.12

@nmpotashnikoff спросил, сталкивался ли кто-нибудь с проблемой сравнения двух текстовых pdf-ов с тем, чтобы на выходе был отчёт (текстовый или pdf’ский )? Варианты: попробовать https://helpx.adobe.com/acrobat/using/compare-documents.html, https://www.diffchecker.com/pdf-diff, http://www.qtrac.eu/diffpdf.html и http://www.linuxandubuntu.com/home/compare-pdf-files-with-diffpdf-in-ubuntu-linux-debian-fedora-other-derivatives, вот эту либу можно включить в CI https://www.inetsoftware.de/products/pdf-content-comparer.
Найденное решение (спасибо @SuckMyNuts): постраничный diff https://github.com/JoshData/pdf-diff, на выходе дает png.

30.12

Обзор HAT решений: https://www.indoition.com/online-help-authoring-tools-survey.htm

Ноябрь'19 в Docops чате

2019-12-18T06:45:32.377Z

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

локализация и версионность в Sphinx

отдельный канал для docops вакансий

генерация диаграмм из кода

оформление скриншотов

выбор ssg под задачи

оценка техписов при найме

1.11.

@olegkovalov пошарил ссылку на статью How to Write Good Documentation (And Its Essential Elements) https://www.sohamkamani.com/blog/how-to-write-good-documentation/
@factorized добавил еще ссылку на эту тему: https://github.com/noffle/art-of-readme
@me_iz_unicorn поделилась PDF версией книги Objective thinking: https://drive.google.com/file/d/10dTb-sqCnbvzZyD-zac-ciCVWJU5TzKA/view?usp=sharing

4.11.

@ayemelianov поинтересовался, не приходилось ли кому-то писать lua-фильтры для пандок. @Roman_Bug поделился ссылкой на статью на тему: https://habr.com/ru/post/474826/ @ayemelianov рассказал, что поэкспериментировал с написанием таких фильтров. С ними есть проблема, что если в документе есть Table of Contents, оно почему-то не отображается.

12.11.

Что обсуждали: Sphinx-doc и локализация, отдельный канал для docops-вакансий.

@exebeeche поделилась проблемами с локализацией через .po/mo файлы в связке sphinx-doc & rst:

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

и спросила, какие есть альтернативы с поддержкой локализации, выгрузки в PDF и версионирования.

@Nick_Volynkin предположил, что второй пункт может быть из-за отсутствия очистки окружения между сборками. Оказалось, что проблема с показом русских превьюшек - это проблема кеша на cloudflare, где лежит инфраструктура.
Участники чата накидали еще вариантов, как верстать PDF: Antenna House, XEP от RenderX (пример: https://www.w3.org/), Antora.

@Nick_Volynkin сообщил, что у основного канала появится его брат с вакансиями в области docops @docops_jobs. С описанием задач, технологий и пользы от документации, а не задолбавших всех печенек. Но не сегодня. Как-нибудь доберусь. А пока что подписывайтесь. :).

Участники чата предложили взять за образец шаблон написания вакансии из @normrabota (ссылка на шаблон: https://docs.google.com/forms/d/e/1FAIpQLSd9mi0OA0urbhTFLtQWu1Cx4Rnu71VMkKbqjDFVluhgeOUIJw/viewform), чтобы вакансии содержали описания с точки зрения или техписа, или проектной команды - стек, скоуп задач, перспективы документационного проекта и описанную пользу для бизнеса, например, вот тут мы хотим базу знаний, чтобы снять нагрузку с техсаппорта. А вот там нужно писать полумаркетинговые тексты, чтобы продвигать технологию. Метрики такие-то, цели такие-то.

14.11

Что обсуждали: снова локализация и поддержка версионности в Sphinx, тесты и тестовые задания для техписателей, правила оценки кандидатов.

В ответ на вопрос от 12.11 предложили отвязать процесс локализации от Sphinx: делать локализацию rst-файлов, и из них делать независимые сборки документации под каждый язык.
@DarthVader предложил для локализации использовать Trados с нормальным управлением проектом, терминологией и версиями локализации. https://t.me/docsascode/11067
@Nick_Volynkin написал, что для локализации rst-файлов нужно по контенту построить синтаксическое дерево (AST) и из его узлов вытащить строки. Это уже реализовано в Sphinx, в ином сценарии придётся делать это с нуля.
Plesk для локализации используют стандартные sphinx-build -M gettext и sphinx-intl, а потом собираем файлы .po в один файл .xliff, который понимает в том числе Trados. Обратно в переведенный .rst он не умеет, но можно научить.
@exebeeche поделилась, что они попробовали через движок с темы readthedocs, там нормально всё билдится, но английский язык надо выделять в отдельную репу в .rst формате. https://t.me/docsascode/11077 Однако, остается проблема - не работает версионность из коробки.

У нее два аспекта (https://t.me/docsascode/11081):

1. В теме нет нормального селектора версий. Это решается днём работы фронтендера.
2. В самом Sphinx нет способа собрать сразу N веток. Это, имхо, чаще всего не нужно.

Версионность плагином sphinxcontrib-versioning не работает с po/mo файлами. Задача: иметь столько веток с русским и английским документами, сколько версий ПО есть, потому что разные клиенты могут использовать разные версии продукта, и им нужна справка именно под их версию, различия могут быть сильные от релиза к релизу. Есть проблема сбилдить английскую ветку из po/mo файлов конкретно под версионность. https://t.me/docsascode/11082
Ранее обсуждали, что Том Джонс из Amazon опубликовал тесты для оценки квалификации технических писателей, так вот он успел в них разочароваться: https://idratherbewriting.com/blog/follow-up-to-technical-writing-tests-post/
Участники чата стали делиться мнением о том, как оценивать квалификацию техписа. Например, @SuckMyNuts считает, что хватает пообщаться на собеседовании и задать наводящие вопросы, про человека ясно сразу почти все.
Согласились, что тесты — это скорее дополнение к тестовому заданию и интервью, чтобы сравнить наиболее сильных кандидатов. Для Amazon они нужны из-за большего потока кандидатов.
@factorized поделился правилом оценки кандидатов:

- кандидаты без опыта или с опытом работы техписателем порядка 1-2 лет: длинное и сложное тестовое (10-20 часов), проверяющее в первую очередь умение разбираться в сложных предметных областях
- кандидаты с опытом 3-4 года: несложное тестовое примерно на час работы
- кандидаты с опытом 5+ лет: без тестового, только собеседование (потому что с такими людьми по разговору действительно всё понятно)

Сколько времени адекватно тратить на тестовое задание? Участники чата разошлись во мнениях, кто-то считает, что максимум час-полтора, а если больше, то timebox it if you need to — то есть сделай ровно столько, сколько можешь сделать за это время, другие приводят пример, когда затрачивали 40 часов и более. Нормально ли платить за тестовое задание?
Нужно ли давать фидбек на тестовые задания? Все сошлись, что фидбек нужно писать даже при отказе, некоторые так делают. Дают кандидату пространство для роста. Большинство фидбек не дают. Но и кандидаты сами не просят.

15.11

Обсуждали, кто как называет production на русском языке? Варианты: продакшен, промышленный экземпляр системы, боевая среда, промышленная среда, пром, в документации релиз/релизная версия, в разговорах - прод. Перевод��ть такие термины — то же самое, что пытаться называть пулл-реквест «запросом на слияние». Лучше зафиксировать жаргонное слово как норму. Для заказчиков по ГОСТ есть документ со стандартизированными терминами, но продакшна там нет: http://tran.su/wp-content/uploads/2015/01/IB.-Standartizirovannyie-terminyi-i-ponyatiya.pdf

19.11

Что обсуждали: Как оформлять скриншоты, пределы неформальности релиз ноутов — планы разработки Clickhouse

@Nick_Volynkin спросил, кто как в документации оформляет скриншоты, какие лучшие практики:

Рамочки-тени, увеличенная версия по клику.
Главное качество и читабельность скрина, а стиль зависит от стилей компании.
Гифки, пример документации Сметный офис https://estimate-office-quick-start.smeta.ru/
Как быть, если интерфейс приложения светлый, скриншоты сливаются с текстом.
1px серую тень, т.к. тоже белые скриншоты на белом. Можно мокапы делать, на MAC доступно по умолчанию. Скрины по размеру экрана, необходимые области выделены.
Просто тонкая рамка серого цвета. без тени, без блюров.
js-скриптом картинки открываются в отдельном окне.
Посоветуйтесь с дизайнерами.
Инструмент для создания красивых скриншотов кода в консоли: https://carbon.now.sh/
Инструменты для создания анимированных записей терминала: https://t.me/docsascode/11278

Участники чата поделились ссылкой на планы разработки Clickhouse, написанные в свободном формате и ссылкой на подкаст Подлодки про токсичность (https://overcast.fm/+If7CWNP74).

22.11

Что обсуждали: Рендеринг latex, что использовать в качестве CI для docs as code

@iafan поделился ссылкой на Javascript-библиотечку, которая рендерит MD + Latex https://github.com/susam/texme Пример результата: https://opendocs.github.io/texme/examples/demo.html .
@ramilrem добавил, что texme рендерит математические формулы именно в шрифт, а не в картинку.
Ivan Cheban поделился статьей, в которой рассказывают об автоматизации генерации документации при помощи Jenkins: https://3di-info.com/automate-documentation-publishing-jenkins/ .@Nick_Volynkin прокомментировал, что в статье упущено самое интересное: когда запускается сборка и куда публикуется документация.
Участники чата добавили, что того же самого можно добиться с помощью gitlab ci, он умеет запускать сборки по разным событиям (пуш, тег, пуш в определенные ветки, можно настроить только на пуши в мастер или только на пуши с тегами), только нужно ранеры сконфигурировать. Но если у вас есть работающий jenkins, настройка gitlab ci с нуля выглядит излишне сложной штукой.

23.11

Что обсуждали: Выбор инструмента для сборки и генерации документации

@lejbron поделился ссылкой на статью на Хабре, описывающей генерацию документации по принципам Docs as code https://habr.com/ru/company/youla/blog/459640/
Обсуждали, что выбор инструмента для автоматизации сборки и генерации документации сильно зависит от того, какие инструменты уже есть в компании (vcs, ci, container runner), идея в том, чтобы использовать для документации то, в чем у вас уже экспертиза.

26.11

@Nick_Volynkin объявил, что взялся за написание статьи про переделку журнала изменений Plesk.

27.11

@ayemelianov спросил, что за формат диаграмм .dia и умеет ли их конвертить pandoc. @SuckMyNuts ответил, что можно сконвертировать во что-то промежуточное, типа пнг или свг и дальше с этим работать: http://dia-installer.de/doc/en/re01.html
Hugo поменял встроенный парсер markdown: https://gohugo.io/getting-started/configuration-markup/#configure-markup Но можно переключиться на старый в конфиге blackfriday.

28.11

Что обсуждали: выбор ��нструмента генерации, рисование диаграмм кодом, KaspOS.

@Lananovikova спросила чат, какое решение (SSG) подойдет для задачи документировать архитектурные описания в наборе репозиториев, публиковать в static html, инклуды нужны, сложных таблиц не планируется, поддержка plantuml добавляемая желательна?
Предложенные варианты: Foliant, Hugo, middleman, docusaurus, Антора, bookstack.
Идея: где-то захостить табличку, например на github, где каждый из сообщества кинет пул реквест, указав имя, какие инструменты docs as code юзает и под какие задачи, чтобы можно было обращаться за экспертизой по конкретным тулам.
@ligurio поделился ссылкой на https://www.diagram.codes/ .@SenyaChe вдогонку кинула ссылку на https://code2flow.com/app .@SuckMyNuts напомнил о существовании https://mermaidjs.github.io/mermaid-live-editor/ и http://asciiflow.com/ .

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

Вспомнили, что была идея замутить митап про генерацию диаграмм из кода.
Докинули, что есть еще Enterprise Architect, он умеет генерировать еще и код из диаграмм.
@exebeeche поделилась банком иконок https://www.flaticon.com/
Про хранение svg в git: https://stackoverflow.com/questions/33480883/how-to-hide-svg-diff-in-github-or-show-svg-as-image n