Комментарии 40
А как решался вопрос выгрузки документации в pdf с нормальным оглавлением и размером страниц А4, А№ и т.д. (если вообще такая задача ставилась)?
Если такой опыт был, может подскажите, какой инструмент использовали чтобы в реальном времени формировать превью pdf документа.
---
Вообще вопрос сообществу - есть набор документов (html и или markdown), они формируют документацию - как это можно быстро и хорошо перевести в pdf. Вообще желательно уже на этапе создания документа видеть превью, как оно будет выглядеть в pdf.
Мы не особо используем pdf, наоборот стараемся всю документацию перевести онлайн, чтобы у пользователей не было "точно_последняя_инструкция_fin(5).pdf". Но да, версии оферт, например, надо хранить — тогда мы копируем нужный md-файл в отдельную папку со всеми изображениями, руками делаем оглавление через якори (### <a id="n">) и дальше в любой конвертер md-to-pdf. Но это удобно только для единичных страниц, признаю, глобально мы стараемся не использовать pdf.
А если вам документация понадобится на бумаге в виде одного документа, то вы делаете что?
Пока таких ситуаций не возникало. Думаю, так же из md-файлов сделаем html или pdf через pandoc или подобную утилиту и распечатаем)
Но приоритетным вариантом всё же попытаемся убедить в достаточности онлайн-версии. Можно, например, настроить доступ только из конкретной подсети, если документ не должен быть публичным. Но любые физические артефакты и тот же pdf устаревают слишком быстро, поэтому мы всеми силами стараемся избегать таких документов.
Есть два типа документации - актуальная и отчетная, если для первой онлайн это хорошо, то для отчетной могут быть нюансы, поэтому и нужен pdf, чтобы документ Х созданный 5 лет назад выглядел ровно также, как при подписании с точностью до пробела.
Всё так, храним версии оферт в pdf, но в общем объеме документации генерация pdf пока не требовала оптимизации. Но спасибо за столько вопросов — действительно надо поисследовать)
Мы онлайн-документацию делаем в git, и можем, в том числе, формировать pdf. Недавно потребовалось распечатать на бумаге для госзаказчика, 800 страниц))) Правда титульник печатала отдельно из word.
А расскажете подробнее?) Как именно генерируете? Может, какие-то неочевидные проблемы всплыли?
Использовали gitbook-pdfgen.
Вы правильно выше заметили, при формировании pdf появляются сложности с пониманием актуальности. Поэтому мы тоже держим документацию на одном из поддоменов основного сайта.
Ну и при формировании pdf верстка не слишком красивая, так как у нас довольно много картинок (скриншотов).
На этот случай я бы использовал AsciiDoc.
Для тех кто ещё не определился, советую посмотреть на Asciidoctor + Antora.
Мы тоже этот комплект используем для сборки pdf и docx, последний бывает удобнее в некоторых случаях. А вот сама документация, по крайней мере как сделано у нас, в гите мне не нравится. Документы вроде руководства пользователя или руководства администратора, разбито более мелкие файлы, которые сливаются в единый документ. Так вот, по pdf или docx искать где находится кусок, который необходимо корректировать - то еще удовольствие. Внятных wisywig редакторов, полностью показывающих итоговый документ, прямо из гита, я не нашел.
У Idea адекватное превью, с картинками и таблицами, но да, несколько файлов в один она не соберёт. В целом Jet Brains анонсировали нечто для техписов: https://lp.jetbrains.com/writerside/ — ждём, надеемся)
Отличная статья, нужно попробовать на выходных этот Hugo. Выглядит куда менее проблемным, чем Jekyll с его рубями. Для каких-то мелочей пока крутил Jekyll в качестве генератора, Obsidian отлично подошёл в качестве ненавязчивого редактора (есть мобильная версия в т.ч.). Но начальная конфигурация Jekyll для невайтишника может быть несколько напряжной, вопреки оф.документации. Впрочем с лёту уже столкнулся с тем, что Hugo без темы генерит только XML-файлы и на всё показывает "Нет страницы". И делает это совершенно молча (хоть бы ворнинг написал)
Что касается конвертации документации в PDF/EPUB - это довольно нужная штука, когда хочется например прихранить всё на читалку и почитать на досуге подробнее, не крючась над монитором.
Так гит ныне для РФ не особо вариант...
А как вы решили проблему с поиском по документации?
К hugo можно прикрутить поиск, на практике не помню что использовал, но помню, что есть почти коробочное решение, которое генерирует файл при билде сайта, а потом js из него читает на фронте
Сейчас используем один из стандартных: https://gohugo.io/tools/search/
Но в перспективе смотрим как прикрутить поиск по всему docs.ozon, а не по одному документу — в такое hugo не умеет)
Спасибо! Хороший опыт возьму на заметку.
А я вот далеко не здоровый человек – зрение ни к черту, сердце, да и не только. Правда, я не люблю, когда мне этим в лицо тычут. И когда я вижу такой заголовок, я огорчаюсь и дальше уже не читаю. Чувствую, что меня походя унизили ни за что ни про что.
Спасибо за увлекательную статью!
Почему md, а не adoc? Как то обосновывался выбор?
Md выиграл своей популярностью среди команды и причастных к переезду людей. Посмотрели на adoc, примерили, поняли, что надо привыкать и вникать и ушли в md. Тем более что в ssg в любом случае надо было дорабатывать элементы — так что чистого языка разметки всё равно не получилось бы. Вот и выбрали привычный для команды.
спасибо за ответ!
замечание про SSG с одной стороны верное, с другой — есть специализированные SG типа Antora которые не вносят ничего "сверху" AsciiDoc.
В общем мы пока ещё размышляем. Но ваш опыт полезен.
Мы начинали с markdown, но в итоге полностью перешли на asciidoc, когда наши аудиторы попросили переформатировать таблицы в соответствии с официальными требованиями. К счастью, конвертер автоматический и работа заняла недолго.
У markdown достаточно бедное форматирование и даже подсветки синтаксиса кода нет из коробки. Да, есть расширения и прямое использование html, но это все выглядит полумерами. Например, с помощью asciidoctor у нас есть:
TOC (в markdown требуется скрипт для генерации)
Диаграммы (mermaidjs или PlantUML), gitlab поддерживает автоматически
Include (самое мощное что есть, все примеры кода у нас рабочие и вставляются из реального кода), поддерживается gitlab, вряд ли когда-нибудь будет поддерживаться github
Admonitions (вставки NOTE, WARNING etc)
Спасибо за интересное решение, а можно немножко подробностей про поиск, это плагин hugo + эластик или еще что то ?
Сейчас вот этот используем: https://github.com/nextapps-de/flexsearch. Но изучаем эластик и собираемся переходить на него в обозримом будущем
А шаблон ваш есть в общем доступе?
Нашего — нет, он сильно нами дотюнен. Есть похожий по структуре: https://themes.gohugo.io/themes/hugo-book/
Интересный опыт, спасибо. Мы тоже переносили документацию на генератор статических сайтов. Но из вводных у нас был не Confluence, а конвертация из DITA в статические PDF/HTML. Было неудобно, писал об этом.
Тоже использовали Panodc, но выбрали другой формат: DITA > HTML > PANDOC > ASCIIDOC
Ну и формат решил, дальше было уже всё под него. Генератор называется Antora, тоже поддерживает кастомизацию, тоже отделяет UI от документации. Но UI из коробки приятный, меняли в основном только цвета и размер шрифта. Чтобы отредактировать, не нужно фантастических навыков, основы HTML/CSS.
Удобно, что каждый раздел документации живёт в независимом репозитории, только главный репозиторий содержит конфигурацию, чтобы собрать все остальные в один сайт. Есть чёткая структура, в какой каталог идут изображения, в какой страницы.
Необходимости приправлять исходный код документации шорткодами нет. Например, правая навигация из заголовков формируется автоматически, в соответствии с правилами в UI. А условия для языка можно определить в самом AsciiDoc при помощи ifdef/ifndef.
Ещё один плюс - невероятная поддержка со стороны сообщества и создателя AsciiDoc/Antora. Т оесть можно обойтись без разработки. Если нужна форма обратной связи, всегда можно обратиться за советом в чат или создать issue на Git, скорей всего кто-то такое уже делал и можно взять за образец. Также постоянно появляются интересные новые проекты, которые можно попробовать. Например, навигационное меню через JS.
И подскажите, как вы до сих пор используете Jira/Confluence, когда они либо ушли из РФ, либо их банально не оплатить из-за SWIFT.
Спасибо, очень подробно расписали!
в первой итерации тоже меняли только шрифты и цвета, тоже не требовало разработки, но у Ozon есть своя дизайн-система и вот подогнать под неё уже сложнее;
у нас так же каждый раздел в отдельном репозитории и есть один — с темой, откуда и тянутся стили;
базовые элементы md, например, заголовки, тоже нет необходимости приправлять шорткодами) а вот куски текста, которые должны отображаться по-разному в разных странах — по-моему, даже в DITA надо чуть повозиться с настройками;
и в hugo так же есть файл глобальных настроек, где можно настраивать и сам факт отображение каких-то элементов, и их внешний вид.
Поэтому всё ещё скажу, что md кажется мне проще ADoc, тем более для людей совсем без опыта работы с docs-as-code.
как вы до сих пор используете Jira/Confluence
Вот тут не отвечу — это вотчина наших админов, мы просто используем доступные внутри компании ресурсы)
У меня нет опыта работы с Hugo, но:
Подстроить под дизайн-систему сложнее, согласен. В Antora/AsciiDoc это не сказать, что просто, но при небольшом опыте с HTML/CSS и помощи знающих людей можно свернуть горы. По вашему описанию Hugo/Md схоже.
Не знал, интересно получается.
В DITA нужно хорошенько повозиться, но только один раз, после чего можно использовать повторно. В AsciiDoc это очень просто. Можно сравнить, наверно, с шорткодами, только это встроенная возможность, которой нет в md. Это было решающим фактором при нашем выборе - иметь всё из коробки очень приятно.
Я так понимаю, это стандартная функциональность любого SSG - конфигурационный yaml.
Markdown проще AsciiDoc - согласен. Но ненамного. Базовый синтаксис почти не отличается (разве что вместо ## в adoc ==, вместо 1. - . и т.д. Преимущество AsciiDoc в потенциале для усложнения. Если потребуется, всегда можно открыть коробочку продвинутых функций. По сравнению с DITA AsciiDoc выигрывает в простоте, но не уступает в функциональности. Markdown нужно приправлять чем-то ещё, в чистом виде он очень уступает.
Спасибо за статью, поучительно. А как API описывается, например, вот это?
Тоже через Hugo?
Документация для продавцов переехала на другой фреймворк? Почему?
Делаем документацию здорового человека в Git на примере Docs Ozon