Комментарии 11
жутко заинтриговали, но ничего не понятно. Сейчас как раз присматриваюсь к подобным вещам — есть проект, в котором надо привести в порядок документацию, на два языка и четыре роли пользователей. Вот похоже что то, что Вы описываете дюже смахивает на то, что я ищу. Может посоветуете, где можно попредметнее посмотреть, что бы даже немножко пощупать на конкретных кейсах.
Вы правы, единый источник для вас – идеальное решение! В случае с DITA реализация ролевой документации на одном языке будет выглядеть примерно так: каждый раздел должен быть написал в отдельном файле (топике), внутри файла текст каждой роли выделяется тегом c определенным ID, а при сборке настраивается фильтрация по тегам с этим ID. 4 роли – 4 фильтра. Аналогичным образом можно настроить фильтры и для локализаций, но тут возникают сложности у переводчиков. По этой причине, как правило, локализованные файлы хранят отдельно.
К сожалению, узнать на практике, как это работает, негде. Книг на русском языке нет, только на английском.
К сожалению, узнать на практике, как это работает, негде. Книг на русском языке нет, только на английском.
То, что Вам нужно будет построено либо на LaTeX либо на XML.
Из XML стандартов есть два, подходящих для технической документации (как для софта так и для железа): DocBook и DITA. Лично мне больше импонирует DITA, но DocBook имхо проще на старте.
XML (опять же, имхо) проще для технических писателей. Особенно, если пользоваться хорошими CSS-based XML редакторами. К списку таких редакторов, которые приводит автор я бы еще добавил Arbortext. Но мой выбор здесь — oXygen XML Author, так же как и у автора статьи. Минус один — они все очень недешевы.
Кстати, рекомендую посмотреть:
habrahabr.ru/post/212881/
habrahabr.ru/company/mirantis_openstack/blog/190624/
А помимо хранения в репозитарии еще потребуется CI: сборка, публикации и тестирование. Разработка документации это вам не просто так :)
Из XML стандартов есть два, подходящих для технической документации (как для софта так и для железа): DocBook и DITA. Лично мне больше импонирует DITA, но DocBook имхо проще на старте.
XML (опять же, имхо) проще для технических писателей. Особенно, если пользоваться хорошими CSS-based XML редакторами. К списку таких редакторов, которые приводит автор я бы еще добавил Arbortext. Но мой выбор здесь — oXygen XML Author, так же как и у автора статьи. Минус один — они все очень недешевы.
Кстати, рекомендую посмотреть:
habrahabr.ru/post/212881/
habrahabr.ru/company/mirantis_openstack/blog/190624/
А помимо хранения в репозитарии еще потребуется CI: сборка, публикации и тестирование. Разработка документации это вам не просто так :)
Вы правы, единый источник для вас – идеальное решение! В случае с DITA реализация ролевой документации на одном языке будет выглядеть примерно так: каждый раздел должен быть написал в отдельном файле (топике), внутри файла текст каждой роли выделяется тегом c определенным ID, а при сборке настраивается фильтрация по тегам с этим ID. 4 роли – 4 фильтра. Аналогичным образом можно настроить фильтры и для локализаций, но тут возникают сложности у переводчиков. По этой причине, как правило, локализованные файлы хранят отдельно.
К сожалению, узнать на практике, как это работает, негде. Книг на русском языке нет, только на английском.
К сожалению, узнать на практике, как это работает, негде. Книг на русском языке нет, только на английском.
А почему бы не прибегнуть к полноценному решению, покрывающему все циклы разработки документации? например, это? Они предлагают, как клиентское решение, так и полноценное Web CMS и даже Cloud. Можно бесплатно получить тестовый аккаунт в CLoud и оценить все самим. При этом вам понадобится только два инструмента — браузер и Java (если она еще у вас не установлена). Из прелестей:
— весь цикл разработки документации от создания топиков до их публикации во все известные форматы покрыт одним приложением
— широченный комплекс функциональностей: ревью, переводы (с интеграцией с известными TMS, такими как XTM), брэнчинг и возможность создания снэпшотов (так называемый бэкап всей документации с возможностью внесения точечных изменений), context sensetive reuse (модная штука на базе keyref подхода из DITA 1.2), metadata extraction, и бог знает че еще там есть
— встроенный редактор oXygen Author (лидер на мировом рынке XML редакторов)
— встроенные publication engines: старый добрый DITA Open Toolkit и xmlMind DITA Converter(работает в сотню раз быстрее чем тулкит)
— вполне дружелюбный интерфейс
— всем заинтересованным бесплатная демонстрация возможностей
— весь цикл разработки документации от создания топиков до их публикации во все известные форматы покрыт одним приложением
— широченный комплекс функциональностей: ревью, переводы (с интеграцией с известными TMS, такими как XTM), брэнчинг и возможность создания снэпшотов (так называемый бэкап всей документации с возможностью внесения точечных изменений), context sensetive reuse (модная штука на базе keyref подхода из DITA 1.2), metadata extraction, и бог знает че еще там есть
— встроенный редактор oXygen Author (лидер на мировом рынке XML редакторов)
— встроенные publication engines: старый добрый DITA Open Toolkit и xmlMind DITA Converter(работает в сотню раз быстрее чем тулкит)
— вполне дружелюбный интерфейс
— всем заинтересованным бесплатная демонстрация возможностей
По доброй традиции хаба «Клиентская оптимизация» поинтересуюсь:
— автор, вам известно значение термина, давшего название упомянутому хабу?
— какое отношение этот топик имеет к предметной области, описываемой этим термином?
— автор, вам известно значение термина, давшего название упомянутому хабу?
— какое отношение этот топик имеет к предметной области, описываемой этим термином?
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Внедрение технологии единого источника DITA в компании-разработчике ПО