Re: [gentoo-project] Gentoo Handbooks moving to the wiki

[Manuel Rüger]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 12.12.2014 16:30, Sven Vermeulen wrote:
> 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
>

Hello Sven,

thanks for moving the handbooks to the wiki!

Just two things I noticed:
Do you know if it's possible to get the same "full view" as with prior
xml pages?
https://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?full=1

In addition it would be great if we can export full viewed handbooks
as pdf/epub. I guess mediawiki could support that via extensions. Do
you have any plans for that?

Cheers,

Manuel
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0

iQJ8BAEBCgBmBQJUiw1vXxSAAAAAAC4AKGlzc3Vlci1mcHJAbm90YXRpb25zLm9w
ZW5wZ3AuZmlmdGhob3JzZW1hbi5uZXQ4MDA1RERERkM0ODM2QkE4MEY3NzY0N0M1
OEZCQTM2QzhEOUQ2MzVDAAoJEFj7o2yNnWNciQEP/jxbkyXwO6QYogMzSt7+Khxw
fFK74T4O3zf2MnJdHLjjNWXxvokJk3RiZtwNTWw9LMEN9VjuhOY/DugszSg1VKHd
gOz9z1D1nvdvR79x72d4qo1dgEynhpn6ljMffO07g2fdhTd1XtOXdbibWTxnaCEu
U2iY+1fBsZDwWO4zol0o+aoDQKZ+x7dpJZQ9Z0eR1fZbAyI6pqFW1mfLjDc7ra04
dO+vwjW64y4aTdINOlLP4n6YLISEQ62V4ivrrYJO8Jhl+uG4+zfsVz13N/vI1TeH
2SWIx10p3yRHfUBe2wr2Eyx+g5Ub/0+T+CxLG2BnP7q1eIn8dxI/CE2pudzcyBKc
ql+x1I2LyPEpbsoMOCUSXjLfCOtV0LtceQmXo4M7AoDGJvhBJOAGkdZ4Qyj4s9IG
p6psxA99LOZQTG9iY7FpQw6K5WvH8ntD3UyfaGKpB1GvLAM3P8RGZcWHY6pJAIpy
8fGWVig/vGaa92HNxD8XohZ7phZds8WlNzHRNzRtOQNYPW6h3xmvNmC8RcDhFhQI
ciNGvMxcTvRl8nQtUBlAGoyyBisW+YiCuU8Pd4IAJGNvk6BR6QrpVqoweMA0jKtY
Ort+Pa9uyqMDBaXTPGj583Fap2ON3RUNfPrKHjKsjmKRnHp5tRGQUtFp3ULZdV3V
h20yH0ZWGAZZX6C/1AZK
=/K2g
-----END PGP SIGNATURE-----