Нужна рекомендация - разработка гибкой системы документации, в значительной степени сосредоточена на локализации [закрыто

Question

Я был обвинен в создании системы / платформы документации.

Вот краткий список основных требований:

• Легко локализовано: это нужно будет поддерживать дюжину или так языки из ворот. (Способность не технического персонала для добавления / обновления переводов будет большим плюсом, хотя не требуется 100%)

• Гибкость в выходных форматах: в минимуме обнаженных, мне нужно выводить документы (в целом, либо в выбранных кусках) как PDF и HTML. Бонусные баллы для нативных форматов, таких как файлы справки Windows.

• Управляется и развернута через интуитивно понятный пользовательский интерфейс (Web, в идеале).

Мне интересно, если бы вы знаете какие-либо системы, которые уже поддерживают этот тип вещи? Я не против писать это с нуля, но я бы предпочел не изобретать колесо, если смогу помочь ему.

Два основных кандидата, которые я сталкивался напротив, Документ а также отдых. Отказ Первый, кажется, получил репутацию, ну сосать. Я тоже не знаком, но мне говорят, что отдых доставит мне хорошую часть пути там.

Любые другие предложения? Буду ли мне лучше построить это с нуля?

Answer 1

Я могу порекомендовать Docbook, если вам нужно создать традиционную техническую документацию: книги, разделенные на главы, разделенные на разделы и т. Д. Я думаю, что есть три основных вещей, которые следует учитывать: сам разметки, редактирование инструментов для инструментов и издательской инструментарии.

Разметки. Markup Docbook XML очень всеобъемлющий, содержащий поддержку только для каждого видящегося аспекта, что может быть включено в технологический объем, а затем некоторые. Это включает в себя основные вещи для книг, таких как перекрестные ссылки, сноски и т. Д., а также разметки специально для программной документации, таких как списки программ, справочники и т. Д. Основная ссылка на разметку Docbook: окончательное руководство Норман Уолш и Леонард Мулленер.

Язык содержимого может быть явно размечен lang Атрибуты, так что исходный документ может содержать контент на нескольких языках, а желаемая языковая версия может быть извлечена на этапе обработки.

Уставные инструменты. Из-за чистого размера словаря Docbook, какой-то редактор «схемы« Aware »в значительной степени является требованием. Хороший редактор поможет вам с выбором элементов разметки и убедитесь, что вы производите действительную разметку. Приличный редактор XML сделает, но в зависимости от того, насколько технические авторы вашей документации вы также можете считать что-то более удобное для пользователя. Доступны некоторые редакторы в стиле WYSIWYG. (Я использовал XMLMind XML редактор, И я был довольно доволен этим.)

Издательские инструменты. Фактический стандартный способ генерации вывода из Docbook XML Markup является Docbook xsl. Распределение стилей. Он имеет поддержку Multple Production Formatats, включая HTML, XSL-FO (для вывода PDF), HTML-справки, даже страницы человека. Выходной вывод, генерируемый стилем, может управляться многими параметрами, и первое, что можно проконсультировать, когда вы хотите настроить выход, это Справочная документация распределен с стилями.

Однако, если и когда вы хотите больше контроля над выпущенным выходом, необходимо настроить таблицы стилей XSLT для вашего конкретного использования. Это может показаться несколько пугающим, особенно если у вас нет предыдущего опыта XSLT. Тем не менее, есть отличная бесплатная книга на эту тему: Docbook XSL: полное руководство Bob Stayton.

Для преобразования XSL-FO в PDF вам также понадобится процессор XSL-FO. Есть бесплатный и открытый источник Apahce Fop. А потом есть несколько коммерческих вариантов.

Скорее всего, ваш процесс публикации, вероятно, в конечном итоге выглядит как система сборки для вашей документации. У вас будет автоматизированная система (вероятно, приводимая в действие инструментом сборки, такими как Make или Ant), что приведет к вашему источнику документации в XML и превращает его в желаемые форматы вывода на нужных языках.

---

Таким образом, я бы сказал, что Docbook - хороший выбор, если вы хотите производить линейную книгу, подобную книгу подробную техническую документацию. Основные недостатки - это сложность разметки, которая может представлять значительную кривую обучения для авторов, и которые могут сделать специальные инструменты для авторских инструментов. Кроме того, настраивание выхода от Docbook XSL Stylesheatshies может быть довольно вовлечена.

Если вы хотите производить менее «похожие на книгу» и более «онлайн-подобной» документации - документация темы взаимосвязаны друг к другу - вы можете взглянуть на Дита для другой альтернативы на основе XML. Я не использовал его, но он также поставляется с насадочным для производства различных выходных форматов из XML Markup.

Answer 2

Docbook и RegistuctedText определенно являются двумя крупнейными конкурентами, но Asciidoc. Есть еще один, похожий язык разметки, который читается независимо от разметки. Я более знаком с (и, следовательно, большим сторонником) реструктурированного текста, лично, но asciidoc - это просто еще один вариант.

Учитывая то, что вы описали до сих пор, это звучит как Moinmoin будет хорошо подходит на основании того, что это имеет реструктурированный парсер а также Это может экспортировать страницы в PDF. Отказ Вы должны быть в состоянии извлечь источник и пройти через все другие остальные автономные инструменты по мере необходимости (но вам может потребоваться предварительно обработать их, чтобы разделить любую разметку MOINMOIN).

У Google есть несколько других Результаты для реструктурированного текстука Wiki Если Moinmoin не совсем то, что вам нужно.