Where does the Mageia Documentation come from?

We asked Lebarhon from the Documentation team to write a bit about the work of the team and the various resources that they created for our users. In this article, he presents their work on the “Official Documentation” and the Mageia wiki.

The Mageia Documentation is made up of two parts: the “Official Documentation“ and the wiki. The way they are managed is very different.

Official Documentation and Mageia Wiki

Inside the official documentation, we have the Classical Installer help, the Live Installer help and the NetInstall help. This documentation, directly related to the installation process, is updated and shipped with each new Mageia release. The MCC (Mageia Control Center) help also belongs to the official documentation. It is steadily updated and packaged to join the regular downloaded updates. All the “Official Documentation” is written and validated by Mageia teams and then translated into more than 20 languages.

The wiki follows a very different process. Anyone can subscribe for an account and write, improve or translate a wiki page. The writer is generally somebody who masters a subject and wants to promote it (application, game, tool, settings, tricks, information, …). Anyone wanting to translate a page is welcomed to do so. Most of the wiki pages are translated into 1 to 5 languages – the translation process is still unwieldy, we plan to deploy a MediaWiki extension to simplify it (and then encourage more contributors to translate wiki pages). Mageia teams monitor the wiki to ensure that it is working as it should (and especially prevent and remove spam), but they can’t proofread all pages thoroughly.

Who Writes the Official Documentation?

Mageia’s official documentation depends on the involvement of several teams:

• Docteam, the writers, made up of about 10 people, some of whom are English native.
• i18n, the translators, made up of 1 to 10 people depending on the language (about 20 languages).
• Atelier, they manage the publication and the monitoring of the translation progress.

Teams are run by an elected leader and deputy leader. Any new volunteers are of course very welcome.

The Workflow

The official documentation follows a strict process. First, some weeks before a release, Docteam writes and/or updates the texts in English in the Docbook format using Calenco. That includes doing screenshots of the next release (to match the new artwork in the installer and MCC as well as GUI changes), checking and proofreading by a native English speaker. Then, the English original text is published in the supported formats: html, epub and pdf.

Here, Atelier takes charge of the .po conversion and its transfer into Transifex, thanks to homemade scripts. Translators can then do the translations using either Transifex or whatever tool they prefer instead, and also create the translated screenshots to place them into Calenco.

At last, Atelier can publish the documentation for all supported languages in the above formats and integrate it into the new ISOs (here also, using homemade scripts). The final step is different for the MCC help, since it is not shipped with the release but packaged like any other update.

Nothing of all that exists for the wiki. The writing is done by a volunteer whenever and in whatever language they want. Then, improving and translating are done by other volunteers, if any (no deadline). This isn’t to say that useful information can’t be found on the wiki, quite the opposite is true, in fact, there are many useful guides and help pages included there.

The Future of the Documentation

Although working pretty well, the Mageia teams have some ideas to improve the documentation:

• Going into the documentation in greater depth for the newcomers, by giving more details and troubleshooting help (UEFI, BIOS boot partition, Grub2 settings, Optimus…).
• There are still some of the MCC tools or their specific features that aren’t documented (as they involve exotic hardware)
• We would like to ship the ISOs with a massive troubleshooting section aiming to help people with poor Internet connections (poor access to downloads, forums, help, etc.).
• Recruiting more translators to strengthen the small teams and to offer more translated documentation (mostly in the wiki).
• Recruit more developers to improve the homemade scripts (for example about the official documentation screenshots management) and to update the wiki software for better multilingual support and a better security management.

There is no good distribution without good documentation in many languages and no good documentation without good and large teams. We are relying on you all.