>Generating Eclipse Help with DocBook or DITA

>With the availabilty of the The DocBook Project and the DITA Open Toolkit, there should be no reason that end user documentation is still maintained in HTML files that have to be manually edited. Having it in HTML, just limits the possibile output formats the documentation could be presented. By moving to either DocBook or DITA formats, the documentation is immediately available in multiple potential formats.

The above wiki entries, describe ways in which the end user documentation can be put into either format and then rendered as HTML. One of the concerns that have been expressed by end users of eclipse, is the lack of documentation or current documentation. The problem with maintaining the HTML, is making sure you update the toc.xml files correctly. By moving to DocBook and DITA, these files are updated automatically when the appropriate build scripts are run.

Treate the documentation generation as one would treate code generation or plugins, and the end user documentation can be rebuilt during a normal build process, and kept more current. Maintenance becomes easier, as only the appropriate docbook or dita file needs to be updated, by the programmer responsible.

Advertisements
This entry was posted in dita, docbook, eclipse, xml. Bookmark the permalink.

2 Responses to >Generating Eclipse Help with DocBook or DITA

  1. >Interesting, never heard of DITA before, we’re using a handrolled ruby based ‘stylesheet’ that transforms XML into a variety of formats suitable for consumption in a variety of ways — eclipse help, single page, multi page with a nice toc.XSL at times is a pain to write, the Ruby DSL that we managed to write is quite easy to write and read. I’m hoping to make the toolchain available as an open source project.

  2. David Carver says:

    >Actually the problem most people have with XSLT is that it’s a functional language instead of a declarative language. So it’s a different way of thinking of how to write something. It’s driven off of templates, and if you try to incorporate procedural logic and thinking into it as a whole, it can be frustrating. Once you start thinking of everything as templates and patterns, it becomes much easier and quicker to manipulate the XML using XSLT than in most other languages.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s