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

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