Март

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