Linux, musical road-dogging, and daily life by Paul W. Frields
Documenting the goodness.

Documenting the goodness.

The Fedora Documentation team uses a fantastic tool called Publican for their documentation work. Publican allows people to turn DocBook XML source, a popular and fairly ubiquitous format, into beautiful renderings in HTML, PDF, ASCII, and even RPM. Publican was developed by Jeff Fearn, who works at Red Hat’s office down under in beautiful Brisbane, QLD Australia, and of course a cast of many people who contributed bugs and enhancement requests.

The Fedora Docs team uses DocBook XML for a number of important release documents like the Installation Guide and the Release Notes. By using source in a git repository, they can collaborate quickly on new and existing documents, and Publican helps them quickly produce translatable POT files that our awesome Fedora translation teams turn into localized documents. (That’s the meaning of L10n by the way — “localization.”) The work the Documentation team produces can be turned into dozens of local languages this way.

When Publican originally debuted, it was fairly robust but it did take a while to build things. Recently, though, it’s taken an enormous leap in efficiency, and rendering documents is incredibly fast, which makes the lives of writers, editors, and translators better by a huge margin. When your workflow speeds up by a factor of ten, thanks to the hard work of developers, it does tend to put a smile on your face!

Wait — did I mention the hard work of developers? Well, let me not forget the next step in this toolchain of wonder and majesty: Transifex. The genii over at Indifex haven’t been sitting on their laurels either, and we’re now using a newer branch of their product on our translation site. That allows our translators to work incredibly quickly and efficiently on documentation and software, localizing all of them so that we can bring Fedora’s free software to people all over the world in their own languages.

In fact, the Indifex guys work so fast that they’ve already turned out version 0.8.0 even though we’ve just migrated to 0.7.4 for our translation site. (I hear the transition up to 0.8.0 isn’t difficult, and it’s likely we’ll be doing this in the near future.) I should also note that a bunch of people spent cycles on getting our translation infrastructure updated, including Dimitris Glezos, Mike McGrath, Noriko Mizumoto, Jens Petersen, Diego Búrigo Zacarão, Ricky Zhou, and others. You guys just kick hindquarters all over the place.

The great thing about moving to Transifex 0.7.4 is that it now supports Publican’s method of divvying up POT and PO files for translators. Rather than have just one big file for the original format, and for each language, Publican divides them up. This makes collaborative work easier, and it also increases translators’ morale because their individual and iterative progress is more visible.

As a result the Docs and Translation teams are ready to kick out the jams for the Fedora 13 release. Translators can quickly and easily test their translation; documentation folks can test builds quickly and collaborate faster on content changes; and we can publish the results immediately to package updates which we can push out regularly leading up to the final release of Fedora 13. It’s going to be amazing!


  1. Pingback: Paul W. Frields: Documenting the goodness. | TuxWire

Comments are closed.