About the tool used for making vaading documentation.

I noticed how nice looking is vaadin’s tutorial and on-line book.
I also found by accident some xml source of it, docbook like.

Can you tell us more about how you develop/render the documentation?
Is it a stylesheet producing the html from the xml source?
Is the Vaadin framework used some way in the process?


Book of Vaadin and Tutorial are written in DocBook. Sources and build.xml can be found in
. First standard DocBook stylesheet packege is used to transform XML to XHTML. Then a custom Liferay portlet is used to transform this XHTML to the http://vaadin.com/book. This latter transformation is really simple - mostly selecting correct element in the source and embedding the portlet.

Joonas, are there any GUI tools used to create and maintain chapters or just a good xml editor ?

I think that Marko has written the text mostly in text editor. Maybe some parts are drafted on Open Office first.

The (little) bits I have written have been done using text editors (Smultron, Emacs and Eclipse).

Did you met any problems with documentation support / population during the lifecycle ? The reason why Im asking is that we’re also migrating now to possibly DocBook (previously we were using HelpAndManual as we had a license for the old version) to centralize documentation build process and avoid platform/proprietary software dependencies, so any experience charing would be very interesting.

DocBook is overly complex format to write and maintain documentation in, but I going though the trouble starts to pay off as we can publish for multiple targets: HTML, Eclipse Plugin, Liferay portlet, PDF, printed book, …

Some learned lessons:

  • Commercial XEP seems to be the only FO processor that works. Unfortunately.
  • Be really careful when planning on the tool-chain for drawing and maintaining graphics
  • Use XHTML output for web publishing - then you can do fine-tuning with simple XSLT
  • XSLT for producting XHTML takes ages - producing PDF with XEP for internal reviews is much faster
  • On demand printers (like Lulu) can have really strange problems with fonts. Only way on knowing if the result is good is to order a sample book yourself. Do use Adobe Adobe Acrobat distiller (nothing else seemed to work).

If you have any questions, just ask.

Joonas, thanks a lot for the information !

We’ll be trying out the DocBook with a small internal project. I think, learning for our tech writers might be the main issue to resolve, however,we’ll see :slight_smile: