{"id":3161,"date":"2017-02-22T13:21:11","date_gmt":"2017-02-22T13:21:11","guid":{"rendered":"http:\/\/blog.mageia.org\/en\/?p=3161"},"modified":"2017-03-02T13:55:11","modified_gmt":"2017-03-02T13:55:11","slug":"where-does-the-mageia-documentation-come-from","status":"publish","type":"post","link":"https:\/\/blog.mageia.org\/en\/2017\/02\/22\/where-does-the-mageia-documentation-come-from\/","title":{"rendered":"Where does the Mageia Documentation come from?"},"content":{"rendered":"<p><i>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 &#8220;Official Documentation&#8221; and the Mageia wiki.<\/i><\/p>\n<p id=\"magicdomid6\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">The Mageia Documentation is made up of two parts: the &#8220;<a href=\"https:\/\/www.mageia.org\/doc\/\">Official Documentation<\/a>&#8220;<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">\u00a0and the <a href=\"https:\/\/wiki.mageia.org\/en\/Documentation\">wiki<\/a><\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">. The way they are managed is very different.<\/span><\/p>\n<h3>Official Documentation and Mageia Wiki<\/h3>\n<p id=\"magicdomid11\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Inside the official documentation, we have the Classical Installer help, the Live Installer help and the NetInstall help. Th<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">is<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> 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 &#8220;Official Documentation&#8221; is written and validated by Mageia teams and then translated in<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">to<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> more than 20 languages.<\/span><\/p>\n<p id=\"magicdomid12\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">The wiki follow<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">s<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> 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, &#8230;). Anyone wanting to translate a page is welcomed to do so. Most of the wiki pages are translated into 1 to 5 languages &#8211; 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&#8217;t proofread all pages thoroughly.<\/span><\/p>\n<h3><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h b\">Who Writes the Official Documentation?<\/span><\/h3>\n<p id=\"magicdomid16\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Mageia&#8217;s official documentation depends on the involvement of several teams:<\/span><\/p>\n<ul>\n<li id=\"magicdomid18\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Docteam, the writers, made up of about 10 people, some of whom are English native.<\/span><\/li>\n<li id=\"magicdomid19\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">i18n, the translators, made up of 1 to 10 people depending on the language (about 20 languages).<\/span><\/li>\n<li id=\"magicdomid20\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Atelier, they manage the publication and the monitoring of the translation progress.<\/span><\/li>\n<\/ul>\n<p id=\"magicdomid21\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Teams are run by <\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">an <\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">elected leader and deputy leader<\/span><span class=\"author-a-z70zhz65z6z74zqz85zz76zz81zmcf5pdq\">. Any<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> new volunteers are of course very <a href=\"https:\/\/www.mageia.org\/contribute\/\">welcome<\/a>.<\/span><\/p>\n<h3 id=\"magicdomid23\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h b\">The Workflow<\/span><\/h3>\n<p id=\"magicdomid25\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">The official documentation follows a strict process. First, some weeks before a release, Docteam writes and<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">\/or<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> 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<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">:<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> html, epub and pdf.<\/span><\/p>\n<p id=\"magicdomid27\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Here, Atelier takes charge<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\"> of<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> 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.<\/span><\/p>\n<p id=\"magicdomid29\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">At last, Atelier can publish the documentation for all supported languages in the <\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">above <\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">formats and integrate it in<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">to<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> 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.<\/span><\/p>\n<p id=\"magicdomid31\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">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).<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\"> This isn&#8217;t to say that useful information can&#8217;t be found on the wiki, quite the opposite is true, in fact, there are many useful guides and help pages included there.<\/span><\/p>\n<h3 id=\"magicdomid33\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h b\">The Future of the Documentation<\/span><\/h3>\n<p id=\"magicdomid35\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Although working pretty well, the Mageia teams have some ideas to improve the documentation:<\/span><\/p>\n<ul>\n<li id=\"magicdomid37\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Going into the documentation in greater depth for the newcomers, by giving more details and troubleshooting help (UEFI, BIOS boot partition, Grub2 settings, Optimus&#8230;).<\/span><\/li>\n<li id=\"magicdomid38\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">There are still some <\/span><span class=\"author-a-z70zhz65z6z74zqz85zz76zz81zmcf5pdq\">of <\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">the <\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">MCC tools <\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">or their specific features <\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">that aren&#8217;t documented (<\/span><span class=\"author-a-z70zhz65z6z74zqz85zz76zz81zmcf5pdq\">as <\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">they involve exotic hardware)<\/span><\/li>\n<li id=\"magicdomid39\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">We would like to ship the ISOs with a massive troubleshooting section aiming<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\"> to help<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> people with poor Internet connection<\/span><span class=\"author-a-z68z2z85zyaa2z89zixc5z81z5z73zq\">s<\/span><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\"> (poor access to downloads, forums, help, etc.).<\/span><\/li>\n<li id=\"magicdomid40\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">Recruiting more translators to strengthen the small teams and to offer more translated documentation (mostly in the wiki).<\/span><\/li>\n<li id=\"magicdomid41\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">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.<\/span><\/li>\n<\/ul>\n<p id=\"magicdomid42\"><span class=\"author-a-asz67zv9z79z1z80zz68z8z87zz71zb22h\">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.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 &#8220;Official Documentation&#8221; and the &hellip; <a href=\"https:\/\/blog.mageia.org\/en\/2017\/02\/22\/where-does-the-mageia-documentation-come-from\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":34,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":true,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","enabled":false},"version":2}},"categories":[157,170,47,153,29,22],"tags":[],"class_list":["post-3161","post","type-post","status-publish","format-standard","hentry","category-atelier","category-collaboration","category-community","category-documentation-team","category-i18n","category-team"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/p159kA-OZ","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/posts\/3161","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/users\/34"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/comments?post=3161"}],"version-history":[{"count":4,"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/posts\/3161\/revisions"}],"predecessor-version":[{"id":3166,"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/posts\/3161\/revisions\/3166"}],"wp:attachment":[{"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/media?parent=3161"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/categories?post=3161"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mageia.org\/en\/wp-json\/wp\/v2\/tags?post=3161"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}