Gentoo Archives: gentoo-project

From: Sven Vermeulen <swift@g.o>
To: gentoo-project@l.g.o
Subject: [gentoo-project] Gentoo Handbooks moving to the wiki
Date: Fri, 12 Dec 2014 15:30:44
1 Hi all
3 The last few days I have been spamming #gentoo-wiki with numerous edits,
4 translation tagging, new pages, and so on, with the main goal to copy the
5 current Gentoo Linux handbooks to the Gentoo Wiki. Before doing the last
6 steps (i.e. updating links and marking the current handbooks as obsoleted) I
7 thought about informing the broader development community about the change.
9 You might ask "why move them to the wiki?" (or perhaps you just say "about
10 time" - in that case ignore the next few paragraphs and jump immediately to
11 "what is the result" further down in the mail ;-), well let me tell why.
13 First of all, the Gentoo Handbooks were the only user-oriented documents
14 that the Gentoo Documentation Project "manages" that were not on the Gentoo
15 Wiki yet. And although 'back in the days' the choice for the XML-based
16 documentation development was valid (offline development of documentation
17 was a primary concern) times have changed, as well as documentation
18 developer abilities.
20 The need to train users into the dark corners of GuideXML (and the almost
21 programmatic approach to the Gentoo Handbooks) pushes down hard on the
22 team's growth. And that in essence is the second reason as well: the Gentoo
23 Documentation Project is no longer the huge project it once was. We reduced
24 from over 20 authors/editors to only one or two active members - and even
25 those do not do it "full time" anymore. Moving towards a better known (and
26 popular) documentation platform makes sense.
28 Any request to update the handbook (we have a few bugs open on it) had to be
29 taken by those few documentation developers, whereas with the move to the wiki,
30 I hope that other developers would take up the opportunity to update the
31 documentation themselves. Especially for the architecture teams who would
32 like to update the Gentoo Handbooks with their specific installation
33 instructions will this be a blessing (I hope). Also the developers in charge
34 of the "additional sections" of the handbook, such as networking, can now
35 help update and maintain the documentation.
37 A third reason is that the current website runs an XSLT parser to transform
38 the documentation into HTML. The Gentoo Handbook being in GuideXML kept on
39 hindering any progress on the website development and future as it was a
40 blocker for potential infrastructural changes. With the move to the Gentoo
41 Wiki, this is one less concern to think about.
43 Of course, consolidating all documentation (including the handbook) to the
44 wiki provides a common platform for Gentoo's documentation development and
45 single writing style. And it gives a universal look and feel to the
46 documentation, instead of having two different views (GuideXML rendering and
47 Wiki rendering look different), which hopefully puts a bit less confusion to
48 the users.
50 An advantage is also that the links to the Gentoo Handbook become a bit
51 simpler. Consider the link to configuring GRUB2 for AMD64:
53 Current handbook:
55 Wiki handbook:
58 Although a tad longer, the link is much more readable, and when pasted on
59 things like IRC users can immediately see what it is about.
61 So, what is the result of this move?
63 The various handbooks are available in their own namespace (with thanks to
64 Alex Legler for creating it as well as supporting the move):
76 If I am not mistaken, these locations should be editable by developers and
77 trusted contributors (and if not yet then that is the idea to implement).
79 All handbooks use the same structure. In effect, there is lots of re-use of
80 documentation snippets (as was the case with the Gentoo Handbooks in
81 GuideXML). Although I did not implement the same "programming-like"
82 documentation development as was done with the GuideXML ones, the wikified
83 Gentoo Handbook uses transclusion (inclusion of other pages) and Semantic
84 MediaWiki for the dynamic generation and changes of documentation.
86 Unless people object heavily, I will start updating the GuideXML handbooks
87 to redirect the users to the wiki handbooks, as well as update the links on
88 the website and wiki articles.
90 Note that, when moved, the translations might take some time to catch up.
91 This is because the translated information (in GuideXML) cannot be easily
92 moved towards the wiki (with the move, texts have been updated as well to
93 reflect the wiki writing style), and because the wiki uses a translation
94 extension that supports parallel translation development - but different
95 than how GuideXML translations worked.
97 Users interested in the "development" side (what are the reused parts and so
98 on) can feed their lusts on
101 I hope this is a start of many updates and improvements. Feedback is always
102 welcome of course.
104 With kind regards
106 Sven Vermeulen
107 aka SwifT