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

Участников чата на день публикации: 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