Tool to write and maintain printed documentation

Question

Some of our customers ask for end-user documentation in a format that’s suitable for printing. Currently, I use Microsoft Word 2002 to write the documents and a non-free PDF printer to generate a PDF file with searchable bookmarks. Then I store both files in the Subversion repositoryT. While it does the job, it has a few drawbacks:

• It is not version control friendly. More specifically, I cannot port changes between branches and it’s very difficult to handle branded stuff such as logos or screen captures.
• I sometimes forget some of the manual steps required to generate the output and the table of contents is missing from the PDF file.

I need a tool that works on Windows, allows to maintain parallel branches of the same document, offers a simple method to handle images (external files would be a plus) and generates high quality PDF files with searchable bookmarks. I’d also appreciate if it’s free or open-source and has a reasonable learning curve.

The goal is to produce printable end-user manuals for PHP-powered intranet sites, I’m not looking for online docs or an API documentation tool. What are your recommendations?

Answer 1

I like DocBook + your preferred SCM tool (Subversion) for this type of work. It's possible to generate html and pdf output from single source (using xsl transformations + some FOP processor). DocBook is not simple to start with, but it is really powerful.

Answer 2

We use LaTeX for generating Documentation. You can generate any Type of Document...PDF etc. All the Documentation is stored in an extra SVN. So it is easy to inform customers about changes in the Documentation.

Additionly your team can work all together on the documentation and your need of several branches is fulfilled.

Ours docs are built regulary by Hudson.

Answer 3

See a huge list of documentation tools here:

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

I used to use Doc-O-Matic for my Delphi projects, and really liked it a lot - but was quite a few years ago. #2 in our evaluation back then was Help & Manual which scored nearly as high as Doc-o-Matic.

Both are commercial tools, but in the long run, they're worth every penny they cost you up front.

Answer 4

That may be a bit overkill but I'd recommend LyX. It is a cross platform, OSS, user friendly frontend to LaTeX.

The "source" files for the documentation are in text and version control and merge friendly. And using LyX instead of LaTeX directly is a great plus in term of learning curve.

We used it already for small group documentation and the ability merge in version control was a real benefit.

Answer 5

Have you considered LaTeX. Due to it's source-based nature it is quite friendly to SCM and there are very powerful functionalities and packages for PDF export, maintaining glossaries, acronyms, auto TOC generation, embedded source code etc.

Answer 6

I would advice to use LaTeX and a good workflow script or Makefile (e.g., the latex-makefile project on Google code) to handle for you dvi/ps generation with the right number of compilations. Also for the great simplicity of handling local revisions, Mercurial is much simpler to setup/use than svn, as simple as hg init, hg add , hg commit! Your training is completed here :-). It reminds me of how I was using RCS locally for my own needs on LaTeX and source files. It is also very easy to create branches or simply clone repositories when a parallel edition of the doc is necessary.

If you would prefer to stay in the wysiwyg world, an other solution for a better revision control would be to use Open Office and the OOoSVN extension which allows to store revisions of the (bigger) uncompressed XML files but with real handling of diffs, contrary to what happens when storing binaries. Not as clean as the first solution IMHO but this solution would avoid translation of legacy docs and the LaTeX learning curve (which, to be honest, is not steep at all).

Hope it'll help.