Building a Documentation System

Question

I am part of a large organization in the insurance industry. I am currently looking at the way we manage our internal product documentation and I want to get some feedback for the community.

We currently author documents using Word, Excel, Publisher, and PowerPoint. If we want to create a "training manual" we simple copy and past this information into a big word document and then print it as a PDF. Oh the joy!

This means that all our documentation, internal and external, is trapped in .doc or .pdf files and you can just imagine how fun it is when we have an update!

My primary concerns are:

• Updatability - I want once source to update and then generate PDF, HTML, etc
• Portability - I want the same "article" or topic to be reorginized for different purposes training vs daily reference
• Open Standard - I want get get away from the Microsoft products

I am currently looking at DocBook, DITA, and maybe even a wiki but would also like to get your input on this subject.

What are your thoughts on this type of project ? What solutions have you used to provide documentation for your products ? Is Docbook or DITA worth the investment of time ?

Answer 1

Look closely at RST and the Python-based Docutils pipeline. Specifically Sphinx.

You don't have to be a Python programmer to use these tools.

Nor, for that matter, do you have to learn XML or DocBook markup.

RST is very, very simple. The files are plain text. You can use include directives to share text snippets effectively.

You can use S5 to generate PPT-line slides from your RST-markup documents. Docutils generates slides nicely.

Answer 2

I imagine that will not be easy to change the documentation method in a large company: if this is true, Open Office can be usefull because is similiar to Office and users will not have so many difficulties. Even the convertion of previous docs is easy, while to handle the docs you can use a document manager like Knowledgetree http://www.knowledgetree.com or Owl http://owl.anytimecomm.com/

While, if the company accepts a deeper change and can train all people, you could think about a wiki or a cms.

If your company has well-defined procedures for the common processes I'd think to something more personalized than a cms or wiki, something like a custom application or a customized Erp http://www.openerp.tv/

Answer 3

We have recently finished an implementation of the Daisy CMS, and we have been very pleased with it. It's a database-backed document repository with a Wiki front end. Daisy is very customizable, is open source (runs on the Java stack), and has some great features out of the box, such as:

• Export to PDF and standalone HTML
• Sophisticated access control
• Translation management
• Lucene-powered full text search (indexes attachments, too)
• Faceted browsing
• ReST APIs

Answer 4

I use TeX (mostly LaTeX) because it is extremely powerful and I can get my documents exactly the way I want them. Converting to PDF is trivial, and if you stick to vanilla LaTeX you can get decent HTML out using a tool like Hevea. Knuth's book on TeX is clear and comprehensive, so you can learn to use all that power. Finally, the underlying platform is rock-solid stable and produces identical results on all kinds of machines.

This choice is not for everybody, but since you are asking on a programming forum, you should have the courage to abandon the WYSIWYG paradigm and treat your documents as programs, you can reap the rewards.

(This is not to say that TeX is perfect or is the best choice for everyone. There are other honorable systems out there. But TeX is well done, and since I use mathematics to describe some of my programs, it is clearly a superior alternative.)