Need advice - Developing a flexible documentation system, heavily focused on localization

Question

I've been charged with building a documentation system/platform.

Here's a short list of the major requirements:

• Easily localized : This will need to support a dozen or so languages out of the gate. (the ability for non-technical personnel to add/update translations would be a big plus, though not 100% required)

• Flexibility in output formats : At the bare minimum, I need to output the documents (either as a whole or in selected chunks) as PDF and HTML. Bonus points for native formats like Windows Help Files.

• Managed and deployed via an intuitive user interface (web, ideally).

I'm wondering if you folks know of any systems out there that support this type of thing already? I'm not averse to writing this from scratch, but I'd rather not reinvent the wheel if I can help it.

The two major candidates I've come across thus far are DocBook and reST. The former seems to have garnered a reputation for, well, sucking. I'm unfamiliar with either, but I'm told that reST would get me a good portion of the way there.

Any other suggestions? Would I be better off building this from scratch?

Answer 1

DocBook and ReStructuredText are definitely the two largest competitors, but Asciidoc is another, similar markup language that is readable regardless of the markup. I'm more familiar with (and therefore a larger proponent of) ReStructuredText, personally, but Asciidoc is just another option out there.

Given what you've described so far, it sounds like MoinMoin would be a good fit on the basis that it has a ReStructuredText parser and it can export pages to PDF. You should be able to extract the source and run it through whatever other standalone tools as necessary (but you might need to preprocess them to strip out any MoinMoin-specific markup).

Google has a few other results for ReStructuredText wiki if MoinMoin isn't exactly what you need.

Answer 2

I can recommend DocBook if you need to create traditional technical documentation: books, divided into chapters, divided into sections, etc. I think there are three main things to consider: the markup itself, the editing toolchain, and the publishing toolchain.

Markup. The DocBook XML markup is very comprehensive, containing support for just about every imaginable aspect what might be included in a techical volume and then some. This includes the basic stuff for books like cross-references, footnotes, etc. as well as markup specifically for software documentation, like program listings, reference entries etc. The essential reference to the markup is DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner.

The language of the content can be explicitly marked up using lang attributes, so that the source document can contain the content in multiple languages, and the desired language version can be extracted at the processing stage.

Authoring tools. Due to the sheer size of the DocBook vocabulary, some sort of "schema-aware" editor is pretty much a requirement. A good editor will help you with the choice of markup elements and will make sure you produce valid markup. A decent XML editor will do, but depending on how technical your documentation authors are, you might also want to consider something more user-friendly. There are some WYSIWYG-style editors available. (I have used XMLMind XML Editor, and I was pretty happy with it.)

Publishing tools. The de-facto standard way of generating output from DocBook XML markup is the DocBook XSL stylesheet distribution. It has support for multple output formats, including HTML, XSL-FO (for PDF output), HTML Help, even man pages. The output generated by the stylesheet can be controlled by many parameters, and the first thing to consult when you want to tune the output is the reference documentation distributed with the stylesheets.

If and when you want more control over the produced output, however, you need to customize the XSLT stylesheets for your particular use. This might seem somewhat daunting, especially if you don't have prior experience of XSLT. However, there's an excellent free book available on the subject: DocBook XSL: The Complete Guide by Bob Stayton.

For converting XSL-FO to PDF, you'll also need an XSL-FO processor. There's the free and open source Apahce FOP and then there are multiple commercial options.

Most likely, your publishing process will probably end up looking like a build system for your documentation. You'll have an automated system (probably driven by a build tool like Make or Ant) which will take your documentation source in XML and turn it into the desired output formats in the desired languages.

---

In summary, I would say that DocBook is a good choice if you are looking to produce linear book-like, detailed technical documentation. The major downsides are the complexity of the markup, which can present a considerable learning curve for authors, and which may make special authoring tools necessary. Also, customizing the output from the DocBook XSL stylesheets may get quite involved.

If you are looking to produce less "book-like" and more "online-like" documentation -- documentation topics interlinked to each other -- you might want to have a look at DITA for another XML-based alternative. I haven't used it, but it also comes with a toolchain for producing various output formats from the XML markup.