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.

This entry was posted in Atelier, Collaboration, community, Documentation Team, i18n, team. Bookmark the permalink.

Curious about Mageia? Download it, give it a try and tell us how you feel about it.

Want to bring something to it? Learn how you can contribute and donate.

14 Responses to Where does the Mageia Documentation come from?

  1. LSDM says:

    Hello, registered for years to participate in the French wiki, I have never been contacted.

    • lebarhon says:

      Being registred doesn’t mean you will be contacted, it only means you are able to write in the wiki. You can do that without join a Mageia team.
      If you want to come and join us, you are welcome, have a look here :
      choose the mailing list(s) matching where you want to help, for example doc-discuss for the documentation team (wiki), or i18n-fr for translation in French… Subscribe and say hello, people will give you all information you need and something easy to start with.

  2. Pingback: Звідки береться документація до Mageia? | Mageia Blog (Україна)

  3. As an alternative to Transifex I can recommend the localization platform https://poeditor.com
    It’s free to use up to 1000 strings to localize apps or websites and has no limits in terms of projects, languages and contributors an account can have (even free accounts).
    The translation interface is really nice too.

  4. Pingback: De onde vem a Documentação da Mageia? | Mageia Blog (Português)

  5. Pingback: Waar komt Mageia’s documentatie vandaan? | Mageia Blog (Nederlands)

  6. Hoyt Duff says:

    I contributed to the Mandiva 7 documentation. It was very rewarding work.

    • Filip says:

      You’re more than welcome to return ;).

      • Hoyt Duff says:

        I did just now subscribe to the doc maillist. I would prefer to work on the wiki; you can see that kind of documentation on my website. What made me leave the doc team back then was the insistence I learn LaTex.

  7. Pingback: Weekly roundup – 2017, week 8 | Mageia Blog (English)

  8. Pingback: Wöchentliche Neuigkeiten – 2017 – Woche 8 | Mageia Blog (Deutsch)

  9. Pingback: Wie wird die Dokumentation von Mageia erstellt? | Mageia Blog (Deutsch)

  10. Pingback: ¿De donde viene la documentación de Mageia? | Mageia Blog (Español)

  11. Pingback: D’où vient la documentation de Mageia ? | Mageia Blog (Français)