Комментарии 19
Странно, что docbook не упомянут - не рассматривали?
В нашем кейсе заказчик попросил именно LaTeX - поэтому другие варианты сразу отпали. А потом мы поняли, как LaTeX можно использовать еще - старт с готовым шаблоном оказался проще, чем разбираться с новой технологией.
Но про docbook до сих пор не слышали, посмотрим. Спасибо за рекомендацию!
Посмотрите ещё Typst, может понравится.
"Текст вместо WYSIWYG" - т.е. надо не просто документацию написать, но и разметку тоже надо вручную сделать, а потом после сборки просмотреть, что вид нормальный.
Ну, если заказчик оплачивает такой геморрой - то ок. А самим не жаль на такое время жизни тратить?
Есть WYSIWYG внутри IDE, при этом документация все так же остается в виде допустим md
Если честно - не жаль. Жаль, когда в документации WYSIWYG после переноса картинки или добавлении в табличке новой строки начинает все ехать. Особенно больно, когда дока не на страничку, а на 100 - и одна микроправка убивает часы ручного форматирования.
В общем, зависит от объема и навороченности документации: для небольших документов можно обойтись и простыми решениями, но чем сложнее и объемнее документация, тем больше времени вы будете терять на борьбу с WYSIWYG-редакторами вместо собственно работы с содержанием. Мы считаем, что затраты окупаются, так как результат получается "красивым" и предсказуемым. Но, каждой задаче - свой инструмент.
Думал в статье будет про литературное программирование. :) Как насчёт документации непосредственно в коде? И как со внедрением LaTeX в комментарии?
Так ли нужна документация в PDF? Её кто-то печатает и читает с бумаги?
В GNU Emacs есть небезызвестный Org Mode, весьма продвинутая вещь в совокупности с дополнениями на его основе. А ещё есть Texinfo, который как-раз таки создавался для гипертекстовой документации. Смотрели?
Да, документация в коде (Doxygen) здорово дополняет docs-as-code! Но есть еще архитектурные решения, диаграммы потоков данных, гайды по онбордингу и интеграции, спецификации и подобное - вот тут LaTeX очень хорошо подходит.
LaTeX внутри комментариев - звучит интересно, кажется подойдет там, где требуется действительное подробное описание происходящего, мы не пробовали, у нас не было такого rocket science )PDF тут скорее не про печать на бумагу, а про строгую вёрстку, которая не плывет как веб-интерфейс. И да, мы неоднократно сталкивались с требованиям о предоставлении документации именно в виде PDF. А LaTex можно преобразовать и в HTML (через Pandoc), главное тут единый источник - .tex файл (что соответствует общему принципу docs-as-code), а выходной формат можно менять.
Спасибо за наводки, Org Mode и Texinfo действительно выглядят как мощные инструменты! У нас никто не использовал Emacs, поэтому мы пошли путем LaTeX.
А как же Gramax? Это визуальный редактор для Markdown с поддержкой OpenAPI, Mermaid, PlantUML и Draw.io, а историю он хранит в git!
Спасибо за ссылку, приложение многообещающее, еще и open source! Здорово, что есть поддержка популярных диаграмм и графики (Mermaid, PlantUML, Draw.io) и вообще выглядит очень дружелюбно. Попробуем, для небольших и средних док выразительных возможностей точно хватит. Но и LaTeX не забросим - понравились нам возможности полной настройки и автоматизации )
Классная статья и интересный кейс, спасибо!
Я раньше, когда научной деятельностью занимался, на LaTeX только и писал статьи. А когда в техписатели перешел стал больше на Markdown, но по LaTeX скучаю и всегда было интересно узнать, работает ли кто-то в парадигме Docs as Code с LaTeX
Скажу, что вы большие молодцы, да и ваш заказчик большой молодец, что договорились на LaTeX.
Скажите, как в решаете проблемы с медленной сборкой? Я для себя настроил precompiled headers, но они работают у меня только с pdflatex (с другим не получилось из-за шрифтов).
Пока мы не сталкивались с проблемами скорости сборки - на наших документах укладываемся в разумное время. Но ваш опыт с precompiled headers очень интересен, спасибо за наводку (вот она - сила Хабра, когда в комментариях появляются ценные идеи).
Можете поделиться примерными замерами, насколько ускорилась у вас сборка?
Для ускорения можно еще попробовать выносить статичные части документа в отдельные .pdf и подключать через \includepdf. В нашем шаблоне затратна по времени генерация диаграмм из текстового описания, поэтому при билде проверяем, если диаграмма уже была ранее сгенерирована в отдельный pdf, то повторно не перегенерируем ее, а берем уже готовую.
Можете поделиться примерными замерами, насколько ускорилась у вас сборка?
Раза в два. Для CI, пожалуй, не важно, а вот для компиляции по Ctrl-S мне важно.
Для ускорения можно еще попробовать выносить статичные части документа в отдельные .pdf и подключать через
\includepdf
Да, этим я тоже занимаюсь. Думал спросить вторым пунктом, а не стал.
Docs as Code: наш опыт документирования с LaTeX и Dev container