Pull to refresh

Comments 27

Хорошо, что не связались с DITA: очень высокий порог входа, серьёзные ограничения на бесплатных сопроцессорах (apache-fop) и как по мне - низкая скорость работы.

Есть и безусловные плюсы, включая удобные IDE (но дорогостоящие), большую структурированность, жесткие структуры для разных видов топиков. Но порог входа, стоимость владения и внедрения выше.

Серьезная задача. Мы уже некоторое время присматриваемся к 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 мы пришли к тому, что переопределяли на уровне верстки внешний вид генеренной документации и писали интеграционные модули (для относительных перекрестных ссылок и интеграции в общее дерево документа). Но это отдельная история.

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/), в этом смысле мы сочли его менее подходящим по этому параметру и дальше рассматривать не стали.

добрый день, спасибо за статью. "это мы читаем и пробуем"
не было ли потребности схемы вставлять? дро ио может или подобные, спасибо

Добрый день, рады, что оказалось полезным.

Потребность была, мы рисуем схемы в drawio, есть свои библиотеки элементов и правила оформления, согласованные с дизайнерами. Сохраняем и вставляем в документацию в формате svg --- схемы легче и качественнее, чем растр.

А почему не markdown? Там и в VScode есть расширение с wysywig и другие редакторы. Не очень понятна аргументация. Я бы выбирал между rst и md (остальные по тем же критериям что и вы отмёл бы), пока md побеждает.

У MD нет из коробки ряда вещей, которые нам были нужны, но которые есть в стандартном контуре rst+sphinx, включая:

  • Ключевание.

  • Переиспользование фильтрация.

  • Нормальный локализационный стек (съели на этом собаку на предыдущем месте).

  • Стандартный механизм расширения спеки.

  • Логическая разметка (богатый синтаксис rst в отличие от бедного md во многом обладает свойствами логической разметки, что дает гораздо большую гибкость в части управления внешним видом публикуемой документацией).

Да, можно было бы взять какую-нибудь из расширенных версий (коих полно) md с кастомной системой сборки, но у нас был пункт про поддержку сообщества, который сразу был бы сужен в случае любого отклонения от commonmark или gfm

не рассматривали AsciiDoc?

Рассматривали, но он не дошел до финалистов, чуть выше в комментариях детали.

Юрий, а вы можете указать стоимость этого проекта?

Стоимость указать не могу, но могу примерно сориентировать по времени специалистов разных специальностей, вовлеченных в проект, если это интересно.

Мы использовали https://js.wiki
Она позволяет подключить git в качестве хранилища документов.
Это предоставило возможность технически продвинутым пользователям сразу коммитить документы в git, а остальные пользовались web-интерфейсом.

Комментарий ради которого стоило прочитать статью.

Как кучно пошло. Недавно в канале "Yandex Cloud - Официальный чат" пригласили пользователей улучшать доки, форкнул гитхаб репо, посмотрел исходники. И вот эта история.

Добрый день, когда планируется "следующая часть материала "? сп

Sign up to leave a comment.