Some time ago, I announced the ‘Getting Started with Fedora’ handbook which we had published in Czech. I also announced the plan to translate it to English, so that it can be translated to other languages. I asked around who could help me with that, especially to figure out the whole system how to get a translated print PDF from a document written in English. A couple of native speakers offered that they would help with proof reading, thank them for that, but first we need to figure out the whole system.
I spoke with Petr Čech who had done typesetting for the pilot edition. We agreed it wouldn’t be very practical to write up and update the handbook in TeX. He suggested we write it in DocBook which has good converters to TeX. Of course, you can’t create a good print PDF by an automatic conversion, so the TeX sources automatically generated from the DocBook file would be just a start point. Then someone would have to work on it to create an acceptable print PDF. Petr said he could be able to do the Czech and English version, but each localization would have to have a volunteer who would finish typesetting.
There are more markup languages that have converters to TeX, the advantage of DocBook is that it has pretty complex tooling around it, so it’d be easy to hook it up with Zanata for translations. But XML syntax of DocBook puts a lot of people off, that’s why guys from the RH Docs team suggested we use AsciiDoc which we can then convert to DocBook to work with the tooling we need. Now, we are in the phase of exploring if the conversion between AsciiDoc and DocBook is reliable because it doesn’t seem to work quite well for more complex documents. The handbook is rather simple, no tables etc.
We’ve also received feedback about the first edition. The handbook seems to be helpful because we gave it away to new students at the local technical university and they had much fewer questions about Fedora than last year. The most frequent question was: “Why is Fedora being replicated on my computers?” They asked because after a couple of kernel updates they suddenly had 3-4 Fedora entries in GRUB and users don’t have an idea what’s going on there. We should explain this in the handbook.
People also asked if we could cover the installation process more in detail. So in the next edition, we probably will cover at least two most common scenarios: installing Fedora on the entire disk and installing it next to Windows.
The biggest bummer of the first edition is that we link the Czech community portal on several places, even on the back cover, but we recently had a dispute with the owner of fedora.cz domain and had to move the portal to mojefedora.cz. This made all the links suddenly outdated.