Комментарии 27
Хорошо, что не связались с DITA: очень высокий порог входа, серьёзные ограничения на бесплатных сопроцессорах (apache-fop) и как по мне - низкая скорость работы.
Серьезная задача. Мы уже некоторое время присматриваемся к docs-as-code для работы с программной документацией, как следствие нам он нужен в связке с такими инструментами как JavaDoc (позволяет генерировать документацию по специальным комментариям в исходных кодах). В идеале хотелось бы собрать решение позволяющее генерировать как описание программ на основе исходных кодов (для JavaDoc есть доклеты и плагины позволяющие генерировать XML в формате DITA), так и различного рода рукописные концепции, технические задания, руководства пользователей и т.д. И еще, хотелось бы чтобы зоопарк этого решения базировался на открытых программных продуктах.
Не попадалось ли кому нибудь свежего обзора средств docs-as-code? Самое свежее и вменяемое что мне попалось это статья от 2016 года со сравнением некоторых из них https://idratherbewriting.com/2016/10/28/markdown-or-restructuredtext-or-dita-choosing-format-tech-docs/
Связка rst+sphinx (и расширения) позволяет интегрировать внутрь себя API-спецификации и описания Python-кода, для наших нужд пока этого достаточно. Возможно, есть расширения для интеграции комментариев из Java-кода, мы пока не изучали этот вопрос.
С JavaDoc --- в случае с DITA AFAIK мы пришли к тому, что переопределяли на уровне верстки внешний вид генеренной документации и писали интеграционные модули (для относительных перекрестных ссылок и интеграции в общее дерево документа). Но это отдельная история.
А почему не http://github.com/redocly/redoc ?
redoc --- узкоспециализированный инструмент для генерации APIсаний из OpenAPI-спецификаций. В нашем случае основной массив документов --- это руководства, концепции, сценарии использования и прочие самописные документы.
Но для Sphinx есть несколько расширений, которые позволяют интегрировать внутрь самописных текстов генерируемые из кода, в том числе --- из OpenAPI-спек.
ADOC и LaTeX совсем не рассматривались?
LaTeX не рассматривали совсем --- у него посложнее синтаксис и все же специфика больше под печатную доку. Но используем его в качестве исходников для формул (rst позволяет интегрировать latex-разметку), когда они нужны.
ADOC не дошел до финалистов, хотя кажется тоже хорошим решением.
Asciidoctor согласно вашей таблице должен быть среди лидеров.
Что осталось за кадром?
Основное — отсутствие встроенного локализационного контура (в rst это генерация po из коробки) и большая распространенность rst, включая поддержку сообщества (субъективно на базе доступных расширений и ответов на наши вопросы на просторах интернета).
а вас не испугал сильно запутаный и неочевидный синтаксис rst? я прям пытался к нему привыкнуть — но не смог. и люди, с которыми я обсуждал эту проблему говорили о том же.
Тут необходимо уточнение (в понимании, конечно, что RST/Sphinx -- один из однозначных лидеров Docs as Code).
(1) Asciidoc'у не чужда i8n. https://docs.fedoraproject.org/en-US/docs/ (Fedora) использует https://po4a.org/. https://inponomarev.ru/corejava (курс по Java, слайды созданы с помощью asciidoctor-revealjs) использует http://docs.translatehouse.org/projects/translate-toolkit/en/latest.
(2) Community Asciidoc (субъективно, конечно) очень развито и на любой вопрос найти/получить ответ можно достаточно быстро
Наш фокус был на стандартных (встроенных в систему сборки) инструментах с минимальным вмешательством и прикручиванием (и поддержкой) дополнительных инструментов (гибкость open source продуктов подразумевает, что при необходимости можно вклиниться в разные части работы с инструментами в будущем). В официальной документации Asciidoc явно указано, что "Asciidoctor (or DocBook) currently does not support translation of content out of the box. There’s a proposal to integrate gettext (discussion), and suggestions are welcome." (https://docs.asciidoctor.org/asciidoctor/latest/localization-support/), в этом смысле мы сочли его менее подходящим по этому параметру и дальше рассматривать не стали.
добрый день, спасибо за статью. "это мы читаем и пробуем"
не было ли потребности схемы вставлять? дро ио может или подобные, спасибо
А почему не markdown? Там и в VScode есть расширение с wysywig и другие редакторы. Не очень понятна аргументация. Я бы выбирал между rst и md (остальные по тем же критериям что и вы отмёл бы), пока md побеждает.
У MD нет из коробки ряда вещей, которые нам были нужны, но которые есть в стандартном контуре rst+sphinx, включая:
Ключевание.
Переиспользование фильтрация.
Нормальный локализационный стек (съели на этом собаку на предыдущем месте).
Стандартный механизм расширения спеки.
Логическая разметка (богатый синтаксис rst в отличие от бедного md во многом обладает свойствами логической разметки, что дает гораздо большую гибкость в части управления внешним видом публикуемой документацией).
Да, можно было бы взять какую-нибудь из расширенных версий (коих полно) md с кастомной системой сборки, но у нас был пункт про поддержку сообщества, который сразу был бы сужен в случае любого отклонения от commonmark или gfm
не рассматривали AsciiDoc?
Юрий, а вы можете указать стоимость этого проекта?
Мы использовали https://js.wiki
Она позволяет подключить git в качестве хранилища документов.
Это предоставило возможность технически продвинутым пользователям сразу коммитить документы в git, а остальные пользовались web-интерфейсом.
Как кучно пошло. Недавно в канале "Yandex Cloud - Официальный чат" пригласили пользователей улучшать доки, форкнул гитхаб репо, посмотрел исходники. И вот эта история.
Добрый день, когда планируется "следующая часть материала "? сп
Создание системы документирования, или как мы от «ворда» к docs as code за месяц переходили