[gentoo-project] Gentoo Handbooks moving to the wiki

[Sven Vermeulen]

Hi all

The last few days I have been spamming #gentoo-wiki with numerous edits,
translation tagging, new pages, and so on, with the main goal to copy the
current Gentoo Linux handbooks to the Gentoo Wiki. Before doing the last
steps (i.e. updating links and marking the current handbooks as obsoleted) I
thought about informing the broader development community about the change.

You might ask "why move them to the wiki?" (or perhaps you just say "about
time" - in that case ignore the next few paragraphs and jump immediately to
"what is the result" further down in the mail ;-), well let me tell why.

First of all, the Gentoo Handbooks were the only user-oriented documents
that the Gentoo Documentation Project "manages" that were not on the Gentoo
Wiki yet. And although 'back in the days' the choice for the XML-based
documentation development was valid (offline development of documentation
was a primary concern) times have changed, as well as documentation
developer abilities.

The need to train users into the dark corners of GuideXML (and the almost
programmatic approach to the Gentoo Handbooks) pushes down hard on the
team's growth. And that in essence is the second reason as well: the Gentoo
Documentation Project is no longer the huge project it once was. We reduced
from over 20 authors/editors to only one or two active members - and even
those do not do it "full time" anymore. Moving towards a better known (and
popular) documentation platform makes sense.

Any request to update the handbook (we have a few bugs open on it) had to be
taken by those few documentation developers, whereas with the move to the wiki,
I hope that other developers would take up the opportunity to update the
documentation themselves. Especially for the architecture teams who would
like to update the Gentoo Handbooks with their specific installation
instructions will this be a blessing (I hope). Also the developers in charge
of the "additional sections" of the handbook, such as networking, can now
help update and maintain the documentation.

A third reason is that the current website runs an XSLT parser to transform
the documentation into HTML. The Gentoo Handbook being in GuideXML kept on
hindering any progress on the website development and future as it was a
blocker for potential infrastructural changes. With the move to the Gentoo
Wiki, this is one less concern to think about.

Of course, consolidating all documentation (including the handbook) to the
wiki provides a common platform for Gentoo's documentation development and
single writing style. And it gives a universal look and feel to the
documentation, instead of having two different views (GuideXML rendering and
Wiki rendering look different), which hopefully puts a bit less confusion to
the users.

An advantage is also that the links to the Gentoo Handbook become a bit
simpler. Consider the link to configuring GRUB2 for AMD64:

Current handbook:
https://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=10#doc_chap2
Wiki handbook:
https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Bootloader#Default:_Using_GRUB2

Although a tad longer, the link is much more readable, and when pasted on
things like IRC users can immediately see what it is about.

So, what is the result of this move?

The various handbooks are available in their own namespace (with thanks to
Alex Legler for creating it as well as supporting the move):

https://wiki.gentoo.org/wiki/Handbook:Alpha
https://wiki.gentoo.org/wiki/Handbook:AMD64
https://wiki.gentoo.org/wiki/Handbook:HPPA
https://wiki.gentoo.org/wiki/Handbook:IA64
https://wiki.gentoo.org/wiki/Handbook:MIPS
https://wiki.gentoo.org/wiki/Handbook:PPC
https://wiki.gentoo.org/wiki/Handbook:PPC64
https://wiki.gentoo.org/wiki/Handbook:SPARC
https://wiki.gentoo.org/wiki/Handbook:X86

If I am not mistaken, these locations should be editable by developers and
trusted contributors (and if not yet then that is the idea to implement).

All handbooks use the same structure. In effect, there is lots of re-use of
documentation snippets (as was the case with the Gentoo Handbooks in
GuideXML). Although I did not implement the same "programming-like"
documentation development as was done with the GuideXML ones, the wikified
Gentoo Handbook uses transclusion (inclusion of other pages) and Semantic
MediaWiki for the dynamic generation and changes of documentation.

Unless people object heavily, I will start updating the GuideXML handbooks
to redirect the users to the wiki handbooks, as well as update the links on
the website and wiki articles.

Note that, when moved, the translations might take some time to catch up.
This is because the translated information (in GuideXML) cannot be easily
moved towards the wiki (with the move, texts have been updated as well to
reflect the wiki writing style), and because the wiki uses a translation
extension that supports parallel translation development - but different
than how GuideXML translations worked.

Users interested in the "development" side (what are the reused parts and so
on) can feed their lusts on
https://wiki.gentoo.org/wiki/Project:Documentation/HandbookDevelopment

I hope this is a start of many updates and improvements. Feedback is always
welcome of course.

With kind regards

	Sven Vermeulen
	aka SwifT