About the tool used for making vaading documentation.

General
1

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?

Thanks.
John.

2

Book of Vaadin and Tutorial are written in DocBook. Sources and build.xml can be found in
http://dev.vaadin.com/svn/doc/trunk/
. 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.

3

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

4

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).

5

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.

6

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.

7

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:

Dmitri