Инструмент для написания и ведения печатной документации

Question

Некоторые из наших клиентов запрашивают документацию для конечного пользователя в формате, подходящем для печати. В настоящее время я использую Microsoft Word 2002 для написания документов и несвободного PDF-принтера для создания PDF-файла с возможностью поиска закладок. Затем я сохраняю оба файла в репозитории Subversion. Несмотря на то, что он выполняет эту работу, у него есть несколько недостатков:

• Это не совместимость с версией. В частности, я не могу переносить изменения между филиалами, и очень сложно обрабатывать фирменные вещи, такие как логотипы или скриншоты.
• Я иногда забываю некоторые шаги, необходимые для генерации вывода, и оглавление отсутствует в файле PDF.

Мне нужен инструмент, который работает на Windows,, позволяет поддерживать параллельные ветви одного и того же документа, предлагает простой метод для обработки изображений (внешние файлы будут плюсом) и генерирует высокое качество PDF файлов с поисковых закладок. Я также был бы признателен, если бы он был бесплатным или открытым исходным кодом и имел разумную кривую обучения.

Целью является создание печатных руководств для конечных пользователей для сайтов интрасети с поддержкой PHP, я не ищу интерактивные документы или инструмент документации API. Каковы ваши рекомендации?

Answer 1

Это может быть немного перебор, но я бы рекомендовал LyX. Это кросс-платформа, OSS, удобный интерфейс для LaTeX.

«Исходные» файлы для документации находятся в текстовом и контрольном вариантах и ​​слияния. И использование LyX вместо LaTeX напрямую - отличный плюс в плане обучения.

Мы использовали его уже для документации небольшой группы, и возможность слияния с контролем версий была реальной выгодой.

Answer 2

Мне нравится DocBook + ваш предпочтительный инструмент SCM (Subversion) для этого типа работы. Можно генерировать html и pdf-выход из одного источника (используя преобразования xsl + некоторый процессор FOP). DocBook не так просто начать, но он очень мощный.

Answer 3

Мы используем LaTeX для генерации документации. Вы можете создать любой тип документа ... PDF и т. Д. Вся документация хранится в дополнительном SVN. Поэтому легко информировать клиентов об изменениях в Документации.

Дополнительно ваша команда может работать вместе над документацией, и ваша потребность в нескольких ветвях выполнена.

Наши документы построены регулятором по Гудзону.

Answer 4

Смотреть список огромный из документации инструментов здесь:

http://www.stack.nl/~dimitri/doxygen/links.html

я имел обыкновение использовать Doc-O-Matic для моих проектов Delphi, и очень понравилось это много - но было довольно много лет назад. # 2 в нашей оценке тогда был Help & Manual, который набрал почти столько же, сколько Doc-o-Matic.

Оба являются коммерческими инструментами, но в конечном итоге они стоят каждого пенни, который они стоят перед вами.

Answer 5

Считаете ли вы LaTeX. Благодаря своему исходному характеру он очень дружелюбен к SCM, и есть очень мощные функции и пакеты для экспорта в формате PDF, поддержка глоссариев, сокращений, автоматическая генерация TOC, встроенный исходный код и т. Д.

Answer 6

Я бы посоветовал использовать LaTeX и хороший сценарий рабочего процесса или Makefile (например, проект лактевого makefile в коде Google) для обработки генерации dvi/ps с правильным количеством компиляций. Также для большой простоты обработки локальных версий Mercurial намного проще в настройке/использовании, чем svn, так же просто, как и hg init, hg add, hg commit! Тренировка здесь завершена :-). Это напоминает мне, как я использовал RCS для своих собственных нужд в LaTeX и исходных файлах. Также очень легко создавать ветви или просто клонировать репозитории, когда необходима параллельная редакция документа.

Если вы предпочли бы остаться в Wysiwyg мире Иным решением для лучшего контроля версий будет использовать Open Office и OOoSVN extension, что позволяет хранить ревизии файлов (больше) несжатый XML, но с реальным обработка различий, вопреки тому, что происходит при хранении двоичных файлов. Не так чисто, как первое решение IMHO, но это решение позволит избежать перевода устаревших документов и кривой обучения LaTeX (что, если честно, не круто).

Надеюсь, это поможет.