LGM AftermathLGM Aftermath

Posted on May 19, 2008
Tags: , , ,
or: How I learned how to write documentation the hard way.

Current situation

The current situation for the GIMP user manual is this:
  • The user manual is written using DocBook/XML.
  • Each DocBook/XML file contains all translations separated by lang attributes.
When I joined the documentation project back in 2003, we thought, that the separation of author and translator brings unnecessary barriers:
  • Authors can only write in one language (reference language)
  • Translators can only translate a string given by the reference language and are enforced to do only that (translation slaves)
Our model (mixing translations with the actual documentation writing) was superior, because the classic model of translators didn’t exist anymore. Every writer was free to describe a GIMP function or GIMP model in it’s own way. The only problem we had: No translator was able to join us, because the writing of DocBook/XML scared everyone away. Additionally - in the meantime - maintaining all translations became a burden for everyone.

Libre Grafics Meeting 2008

I saw dark clouds coming upon me this time. Me as the one who still defended our model of creating documentation for GIMP. Andy Fitzsimon used the GIMP manual as a bad example of an unmaintainable documentation in his talk. He is right, as well as all the other guys who tried to tell us.

Back in 2007 I couldn’t see, that our way we create documentation was supposed to fail:
  • lack of contributors a.k.a translators. Writing XML as a translator is hard. There are a lot of tools available for translators which provide a very nice and usable GUI.
  • not focusing on one language which will be the reference language. You can only concentrate on one thing and not on eleven other manuals simultaneously.
  • and the worst: Trying to invent the wheel. Tools and Architecture is already developed by others. They do have disadvantages though, but you can’t solve them by creating something new and just thinking, it will be better than other tools because it’s new.
I learned my lesson. We now switch to a system using one reference language and creating translations from this language. Andy Fitzsimon introduced publican as a possible basis, as well as Erik Gebers introducing Scenari. Both noteworthy tools which are interesting to look at.
Blogged with the Flock Browser