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

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