Есть у нас проект, для которого есть некоторое количество документации — как для пользователей, так и для программистов. Сейчас она хранится в вики, это не очень удобно. Вот чего я хочу:
1. Документация должна вестись в текстовых файлах, чтобы ее можно было загнать под контроль версий.
2. Желательно вики-форматирование.
3. Каждый файл — это раздел. Можно в тексте ставить ссылки на разделы и подразделы.
4. Можно вставлять изображения.
5. Всё это должно уметь генерироваться в PDF или DOC с кликабельным оглавлением, с сохранением в тексте форматирования, ссылок, изображений.
6. Желательна возможность онлайн-просмотра текста на сайте (как в обычных вики-сайтах).
Варианты, которые я вижу:
1. Обычный вики-движок. Умеет всё, кроме генерации единого PDF с поддержкой указанных выше фич. Хотя есть плагины, которые добавляют эту функциональность (по крайней мере, для mediawiki), мне результат их работы не нравится. Например, инструмент создания книг на wikipedia.org генерирует некликабельное оглавление, которое не распознается как оглавление, и ссылки, по которым не видно, что они ссылки. Еще одна проблема вики — работать можно только при наличии интернета. А локальные текстовые файлы я бы мог править, когда захочу.
2. TeX. Не сомневаюсь, что реализуемо всё вышеперечисленное (кроме вики-разметки). Но мне не кажется, что это правильный и простой путь. Красиво отформатировать документ в LaTeX для меня — проблема.
3. Взять консольный вики-парсер и допилить под свои нужды. Например, mwlib, который теоретически умеет делать экспорт в PDF. Но я еще не смотрел, что за PDF он генерирует.
Sphinx
Разметка в reStructuredText, каждый файл может быть как разделом, так и страницей, автоматическая генерация оглавлений с произвольной глубиной, поиск по всем документам с помощью JavaScript, шаблонизация, API для расширений, генерация в HTML, Windows HTML Help, LaTeX (для PDF), man pages, plain text.
Sharepoint:
Набор веб-приложений для организации совместной работы
Функциональность для создания порталов
Модуль поиска информации в документах и информационных системах
Функциональность управления рабочими процессами и cистему управления содержимым масштаба предприятия
Модуль создания форм для ввода информации
Функциональность для бизнес-анализа
Посмотрите в сторону doxygen, там нет вики-форматирования и я не уверен что там есть кликабельное оглавление в pdf, но все остальное там точно присутствует.
Doxygen уже используется для документации по классам и методам. Мне кажется, для больших статей он не очень удобен. Кроме того, мне не удалось заставить его создать нормально выглядящий PDF.
А мы использовали DITA -ооочень удобно, всё лежало под контролем версий, и как docbook генерит всё, что пожелаете — главное написать xslt (есть несколько готовых из коробки)
