Отчасти раскрывал вопрос в комментариях к предыдущей статье:
Основное — отсутствие встроенного локализационного контура (в rst это генерация po из коробки) и большая распространенность rst, включая поддержку сообщества (субъективно на базе доступных расширений и ответов на наши вопросы на просторах интернета).
Все нюансы познаются с течением времени, но первые коммиты случаются обычно в течение нескольких дней, причем с минимальным участием наставника. Помогает образцовый документ и инструкции.
Обычно сразу в языке разметки. Так уходит меньше времени на последующее оформление, да и сложностей с отвлечением от сути, честно говоря, не наблюдается.
Ревью техническими писатели — через mr-ы, владельцами знаний — через mr, конфлюенс-аутпут, комментариями в баг-трекере. Подбираем инструмент под удобство и навыки вычитывающих.
Конфликты решаем на локальной машинке, используем стандартные средства гита+редактор (в нашем случае — vs code).
Если ошибки на уровне пайпов в гитлабе/инфраструктуры — привлекаем девопса. Если на уровне сборки — ребята справляются сами или с помощью внутреннего сообщества технических писателей.
Наш фокус был на стандартных (встроенных в систему сборки) инструментах с минимальным вмешательством и прикручиванием (и поддержкой) дополнительных инструментов (гибкость 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/), в этом смысле мы сочли его менее подходящим по этому параметру и дальше рассматривать не стали.
Основное — отсутствие встроенного локализационного контура (в rst это генерация po из коробки) и большая распространенность rst, включая поддержку сообщества (субъективно на базе доступных расширений и ответов на наши вопросы на просторах интернета).
У MD нет из коробки ряда вещей, которые нам были нужны, но которые есть в стандартном контуре rst+sphinx, включая:
Ключевание.
Переиспользование фильтрация.
Нормальный локализационный стек (съели на этом собаку на предыдущем месте).
Стандартный механизм расширения спеки.
Логическая разметка (богатый синтаксис rst в отличие от бедного md во многом обладает свойствами логической разметки, что дает гораздо большую гибкость в части управления внешним видом публикуемой документацией).
Да, можно было бы взять какую-нибудь из расширенных версий (коих полно) md с кастомной системой сборки, но у нас был пункт про поддержку сообщества, который сразу был бы сужен в случае любого отклонения от commonmark или gfm
Потребность была, мы рисуем схемы в drawio, есть свои библиотеки элементов и правила оформления, согласованные с дизайнерами. Сохраняем и вставляем в документацию в формате svg --- схемы легче и качественнее, чем растр.
LaTeX не рассматривали совсем --- у него посложнее синтаксис и все же специфика больше под печатную доку. Но используем его в качестве исходников для формул (rst позволяет интегрировать latex-разметку), когда они нужны.
ADOC не дошел до финалистов, хотя кажется тоже хорошим решением.
Связка rst+sphinx (и расширения) позволяет интегрировать внутрь себя API-спецификации и описания Python-кода, для наших нужд пока этого достаточно. Возможно, есть расширения для интеграции комментариев из Java-кода, мы пока не изучали этот вопрос.
С JavaDoc --- в случае с DITA AFAIK мы пришли к тому, что переопределяли на уровне верстки внешний вид генеренной документации и писали интеграционные модули (для относительных перекрестных ссылок и интеграции в общее дерево документа). Но это отдельная история.
Есть и безусловные плюсы, включая удобные IDE (но дорогостоящие), большую структурированность, жесткие структуры для разных видов топиков. Но порог входа, стоимость владения и внедрения выше.
redoc --- узкоспециализированный инструмент для генерации APIсаний из OpenAPI-спецификаций. В нашем случае основной массив документов --- это руководства, концепции, сценарии использования и прочие самописные документы.
Но для Sphinx есть несколько расширений, которые позволяют интегрировать внутрь самописных текстов генерируемые из кода, в том числе --- из OpenAPI-спек.
Пока поделиться образцовым документом не готовы, но, возможно, решимся в будущем.
Спасибо за комментарий!
Отчасти раскрывал вопрос в комментариях к предыдущей статье:
Основное — отсутствие встроенного локализационного контура (в rst это генерация po из коробки) и большая распространенность rst, включая поддержку сообщества (субъективно на базе доступных расширений и ответов на наши вопросы на просторах интернета).
Все нюансы познаются с течением времени, но первые коммиты случаются обычно в течение нескольких дней, причем с минимальным участием наставника. Помогает образцовый документ и инструкции.
Обычно сразу в языке разметки. Так уходит меньше времени на последующее оформление, да и сложностей с отвлечением от сути, честно говоря, не наблюдается.
Ревью техническими писатели — через mr-ы, владельцами знаний — через mr, конфлюенс-аутпут, комментариями в баг-трекере. Подбираем инструмент под удобство и навыки вычитывающих.
Конфликты решаем на локальной машинке, используем стандартные средства гита+редактор (в нашем случае — vs code).
Если ошибки на уровне пайпов в гитлабе/инфраструктуры — привлекаем девопса. Если на уровне сборки — ребята справляются сами или с помощью внутреннего сообщества технических писателей.
Добрый день,
Спасибо за интерес! Материал в работе, stay tuned :)
Наш фокус был на стандартных (встроенных в систему сборки) инструментах с минимальным вмешательством и прикручиванием (и поддержкой) дополнительных инструментов (гибкость 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/), в этом смысле мы сочли его менее подходящим по этому параметру и дальше рассматривать не стали.
Стоимость указать не могу, но могу примерно сориентировать по времени специалистов разных специальностей, вовлеченных в проект, если это интересно.
Рассматривали, но он не дошел до финалистов, чуть выше в комментариях детали.
Основное — отсутствие встроенного локализационного контура (в rst это генерация po из коробки) и большая распространенность rst, включая поддержку сообщества (субъективно на базе доступных расширений и ответов на наши вопросы на просторах интернета).
У MD нет из коробки ряда вещей, которые нам были нужны, но которые есть в стандартном контуре rst+sphinx, включая:
Ключевание.
Переиспользование фильтрация.
Нормальный локализационный стек (съели на этом собаку на предыдущем месте).
Стандартный механизм расширения спеки.
Логическая разметка (богатый синтаксис rst в отличие от бедного md во многом обладает свойствами логической разметки, что дает гораздо большую гибкость в части управления внешним видом публикуемой документацией).
Да, можно было бы взять какую-нибудь из расширенных версий (коих полно) md с кастомной системой сборки, но у нас был пункт про поддержку сообщества, который сразу был бы сужен в случае любого отклонения от commonmark или gfm
Добрый день, рады, что оказалось полезным.
Потребность была, мы рисуем схемы в drawio, есть свои библиотеки элементов и правила оформления, согласованные с дизайнерами. Сохраняем и вставляем в документацию в формате svg --- схемы легче и качественнее, чем растр.
LaTeX не рассматривали совсем --- у него посложнее синтаксис и все же специфика больше под печатную доку. Но используем его в качестве исходников для формул (rst позволяет интегрировать latex-разметку), когда они нужны.
ADOC не дошел до финалистов, хотя кажется тоже хорошим решением.
Связка rst+sphinx (и расширения) позволяет интегрировать внутрь себя API-спецификации и описания Python-кода, для наших нужд пока этого достаточно. Возможно, есть расширения для интеграции комментариев из Java-кода, мы пока не изучали этот вопрос.
С JavaDoc --- в случае с DITA AFAIK мы пришли к тому, что переопределяли на уровне верстки внешний вид генеренной документации и писали интеграционные модули (для относительных перекрестных ссылок и интеграции в общее дерево документа). Но это отдельная история.
Есть и безусловные плюсы, включая удобные IDE (но дорогостоящие), большую структурированность, жесткие структуры для разных видов топиков. Но порог входа, стоимость владения и внедрения выше.
redoc --- узкоспециализированный инструмент для генерации APIсаний из OpenAPI-спецификаций. В нашем случае основной массив документов --- это руководства, концепции, сценарии использования и прочие самописные документы.
Но для Sphinx есть несколько расширений, которые позволяют интегрировать внутрь самописных текстов генерируемые из кода, в том числе --- из OpenAPI-спек.