Какую CMS выбрать для ведения документации нескольких проектов?

Question

[Dru Dro]

По роду деятельности мне приходится работать со многими инструментами для написания доки, руководств пользователей, руководств разработчиков и других ководств. Каждый день задачи разные, решаемые разными способами и инструментами: от Help&Manual и Microsoft HTML Help Workshop до самописных программок, компилирующих и собирающих хелпы в нужные форматы.
Компания, где я работаю, выпускает множество продуктов для разработчиков под разные цели, языки программирования, IDE, операционные системы, базы данных и т.д. Отсюда и необходимость собирать множество форматов одной и той же справки: PDF, CHM, HXS, DOC, а также онлайн-хелп. И вот настал тот момент, когда для написания документации каждого продукта приходится использовать разные третье-сторонние инструменты, отличающиеся генерируемым форматом справки.
В связи с этим я ищу CMS со следующими возможностями:

• Разделение прав писателей доки в админке. Чтобы каждый участвующий TW мог править свою ветку документации на сайте (по проектам, продуктам, продуктовым линейкам).
  
• Возможность создания и ведения нескольких проектов, с разным дизайном, разными авторами, в идеале - на разных субдоменах или ветках сайта
  
• Экспорт/Импорт/Конвертер различных форматов справки: CHM, PDF, RTF, XML и его подмножеств (FB2/EPUB)
  
• Возможность добавлять отдельные HTML-статьи
  
• Многоязычность
  
• Расширенный WYSIWYG-редактор
  
• ЧПУ
  

Среда реализации не имеет значение, хоть на Delphi - лишь бы могло всё это.
Любой ответ будет полезен.
P.S. если встречали модули для неспециализированных CMS - делитесь ссылками - буду рад потестировать.

Answer 1

[Денис _______________]

xwiki:
- как и любой вики-движок позволяет гибко настраивать права доступа, как по группам, так и для отдельных пользователей;
- нет ничего проще - внутри Сайта вики-движок позволяет создать сколь угодно большое число субвики, со своими локальными/глобальными пользователями, правами, привилегиями, настройками, плагинами, скинами и т.д.;
- по умолчанию позволяет сохранять в pdf любую страницу, если поставить аддон, то якобы (я не тестил лично), можно выгрузить в pdf всю вики. Что касается поддержек других форматов, страницы из pdf, при условии что они набрана в редакторе xwiki, легко копируется в офис с последующим экспортом во все подряд;
- синтакс html поддерживается, как и программные скрипты (Velocity, Groovy, Python, Ruby and PHP), так же есть вариант для html с макросом;
- интерфейс переведен на многие языки, включая русский. Перевод и отображение текстов на русском языке корректен, проблем с кириллицей нет, кроме семантического поиска (формы слова "окно" и "окна" для внутреннего поиска одно это разные слова);
- есть поддержка OpenOffice (необходимо настраивать руками), WYSIWYG-редактор стандартный, при этом удобное переключение (2 вкладки) на обычный текстовый и обратно;
- если речь о ссылках -то:
поддержка русского языка упирается в механизм работы со ссылками, который для русского языка создает ссылки вида:
Wiki Home\Test page\страница с пробелами
http://*Ваш_сайт*/xwiki/bin/view/Test+page/%D1%81%...
На сколько я понимаю — это Unicode, или аналог. В принципе, если не зацикливаться на том что отображается в строке ввода ссылки в браузере, сам движок предложит создать ссылку вида:
[[страница с пробелами>>doc:Test page.страница с пробелами]] — это внутренняя ссылке, хотя он переваривает и внешние вида: http://*Ваш_сайт*/*Ваш_путь*

Comments

[Эдуард Тибет]

Ваш пример: http://*Ваш_сайт*/xwiki/bin/view/Test+page/%D1%81%... - имеет очень много проблем. При изменении title - любые отправленные ссылки становятся недействительными. С точки хрения принципа переносимости адреса должны быть "content agnostic".

[Dru Dro]

можно допилить переадресацию со старых урлов

[Dru Dro]

если opensource)

[Денис _______________]

Вы неправы, потому что внутренняя адресация идет по структуре:
[[страница с пробелами>>doc:Test page.страница с пробелами]]
И любое изменение title меняет во всей вики связанные ссылки. Это раз, а два если Вы переименовываете через Rename страницу это приводит ровно к тому же эффекту, но вот в браузере в строке путь будет по-прежнему отображаться хрень вида:
https://toster.ru/xwiki/bin/view/Test+page/%D1%81%...
Если же Вы будете делать ссылки со сторонних сайтов, то линк они переварят, но любое изменение title в xwiki будет означать и изменение внешней ссылки, а значит широкое поле для изобретении велосипеда, впрочем это справедливо для любого вида внешних ссылок через http://

Впрочем лучший способ снять непонимания - попробовать Самому:
enterprise.xwiki.org/xwiki/bin/view/Main/Download
- качаем zip архив, распаковывем, запускаем start_xwiki.bat и переходим на локалхост, ждем пока прогрузится система и вводим Admin, admin, а дальше тестим.

[Денис _______________]

DruDro: xwiki - это opensource

[Эдуард Тибет]

Внешняя система по умолчанию ничего не будет переваривать - она покажет 404 и все. По мере нарастания контента это будет большой головной болью (про стартапы я не говорю :) - там мало контента. Кстати, Atlassian со своей Confluence уже сталкивается с такой проблемой именно из-за title в url. Если вы посмотрите (вдумчиво) на их хелпы, то количество 404 уже неприлично большое для 6 версий каждого продукта.

Что касается велосипеда, то лучше не изобретать. По умолчанию, имя файла должно быть != title. Т.е. должен быть какой-нибудь uniq ID, который не изменятся со временем. Что касаемо wiki-base, y Atlassian было это в свое время, но они почему-то отказались, чем сделали большие проблемы для компаний (в джире есть целый тред по этому поводу). Другое дело, что им пофигу на это, т.к. показатали дохода и так позволяют не парится о существующих процентах пользователей :)

Что касаемо тех стандартов, о которых я говорю, то там это по умолчанию из коробки. Т.к. title пишется в head html, а название файла - в uri.

[Денис _______________]

Эдуард Тибет: Если я правильно понял читая форумы, поддержку автоматического редиректа запилят в будущем, пока что существуют такого рода костыли (не пробовал лично, но пишут что в принципе реализуемо):
extensions.xwiki.org/xwiki/bin/view/Extension/Uniq...

или, как еще вариант, лепить следующий костыль:
- создается 2 страницы макросом или вручную, одна с уникальным ID, другая с содержимом. Страница с уникальным IDсодержит или редирект на нужную, или же выводит фрейм с содержимым нужной страницы.

[Эдуард Тибет]

Денис _______________: Я согласен, что разные подпорки существуют. Я лишь высказал свое мнение относительно изменяемых URI - это very bad practice.

Answer 2

[Эдуард Тибет]

Формат: Docbook/XML (начиная с 5.1) или DITA
Хранение: GIT/SVN
Authoring tool: любой, к которому адаптируются писатели
Публикация - Apache Cocoon (для realtime публикации), либо скриптовая сборка (если требуется просто "отдавать файла")

По умолчанию присутствуют:
1. Многоязычность.
2. Вывод deliverable в зависимости от цели (аудитория/ОС/заказчик и т.п.)
3. Форматы: PDF, html, ePub, word roundtrip (но требуется доработка).
4. Версионность хранения (diff/merge).

Можно еще долго перечислять, но если действительно заинтересуют подробности (применение каждого пункта, особенности и т.п.), то дайте знать комментом.

Comments

[Dru Dro]

интересует структура сгенерированной веб-страницы. разделение содержания и статьи на фреймы или получается и вовсе одностраничный хелп?
Можно примеры?

[Эдуард Тибет]

Это сематнические стандарты разметки. При использовании этих стандартов ВЫ настраиваете все так, как хотите. В их основе: XML, а также готовые "из коробки" xsl преобразования. Как вы измените готовый xsl (дополните его своим преобразованием), то и будет. Т.е. это управление контентом в автоматическом режиме с помощью xslt-скриптов - полная автоматизация.

При использовании Docbook/XML вы отделяете содержимое и представление. И сосредотачиваетесь на содержимом - текстах, картинках и т.п.. Это называется технология единого источника в технической документации (single sourcing technical documentation) - содержимое имеет семантическую структуру, не связанную с выходным форматом.

Приведу лишь пример. Очень показательный. Вы, наверное, знаете про ГОСТ (2.x, 19.x, 34.x). Так вот. Многие просто изнывают от требований рамочек, страницек и т.п. Одна из команд сделала xsl преобразование для формирования именно ГОСТовский документов (https://bitbucket.org/Lab50/espd-docbook5/overview). Т.е. их одного источника можете получить ГОСТ, а можете что-то свое (в обычном "вордовском варианте" вы не сможете получить это без полного переформатирования).

Суть, надеюсь, понятна?

[Эдуард Тибет]

Правильный линк: https://bitbucket.org/Lab50/espd-docbook5/overview

[Dru Dro]

Допустим, наши разрабы поставят и настроят всё. А сможет потом студентка-техписательница с элементарными знаниями HTML и минимальным опытом ведения блога в WordPress создать проект хелпа, построить дерево статей, заливать медиа-файлы...? В общем, UI админки дружелюбный для чайника?

[Эдуард Тибет]

Вся суть в том, что вам надо совсем отстранить "студентка-техписательницу" от какой-либо структуры и здесь это можно сделать. Т.е. вы даете ей редактор (в моей схеме - Authoring tool) и она там пишет - все. Остальное - цепочки преобразований, топиков и т.п. остается на уровне автоматизации. Здесь только один вопрос - сможет ли она владеть чем-то "не ворд" для набивания текста. По моему опыту - научить реально, хотя и с усилиями.

Вы можете попробовать (просто сделать один шаг) - загрузить www.xmlmind.com/xmleditor evaliation. Посмотреть сюда, как это работает: www.xmlmind.com/xmleditor/tutorial.html Хотя сразу же предупреждаю, что там по умолчанию все основано на gui-действиях и оно дольше, чем сделать keyboard shortcuts.

Вам надо понять только одну вещь - wiki и другие WISYWIG системы хороши для создания контента сотрудниками с нулевым уровнем знаний :) ... но ровно до тех пор, пока контентом не надо управлять. Когда начинается серьезная работа, то без single sourcing уже не обойтись.

Answer 3

[Станислав Салангин]

Atlassian Confluence