Lowering the participation barrier for Fedora Docs

[Eric H. Christensen]

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

On Tue, Nov 12, 2013 at 03:25:01PM +0100, Jérôme Fenal wrote:
> Why don't we have a look at what happens in the JBoss.org space?
> It seems that a lot of docs, also published through DocBook and
> Publican, are initially written in Asciidoc.

Yes, ASCIIDoc can be changed into DocBookXML *but* it's not a complete changeover.  There are many tags that aren't used in the conversion that I use semi-regularly.  But in general it's not a bad swap.  There are limitations of ASCIIDoc, though, that can cause problems (like ASCIIDoc doesn't like more than two authors listed on the page and some of the files don't get rendered in a way that allows Publican to easily digest the files).

> Eric, do you happen to know colleagues in this area who'd be kind
> enough to share his experience here?

I don't know anyone *specifically* in JBoss.org but I can look around and see who I can find.  I don know that ASCIIDoc has been using by Kernel developers for a long time for their documentation.

> Dan Allen, Red Hat employee, and Asciidoc contributor, could be a good
> option for that.

Yes, Dan is big into ASCIIDoctor but I've not been able to follow up with him on the problems that I've found.

In the end, unless we make some sort of magic to create the website Publican is the best solution I've seen (scalability!).  I once advocated ASCIIDoc in the past and still think it's a good way to get the words out the door.  I still think it's a good idea but I also know that it's not as simple as converting it and then building it with Publican.

- -- Eric

- --------------------------------------------------
Eric "Sparks" Christensen
Fedora Project

sparks at fedoraproject.org - sparks at redhat.com
097C 82C3 52DF C64A 50C2  E3A3 8076 ABDE 024B B3D1
- --------------------------------------------------
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.14 (GNU/Linux)

iQGcBAEBCgAGBQJSgj5jAAoJEB/kgVGp2CYvOsUL/2OV0JY/lolMQt2tCq7S3qbs
rc8YShzhB1isPQVEPxAkk9bOfnDMMU5HieRAOTcqZZl8+8ar6whEg/x54Fela4UY
5+jja9CliDuUSVmXhNDiYCqJkQR50gPpxmfxo01gjpcIrQsmjen6sY4nwn5H6tbX
h01tRe87uPYAIsvkMTdope6TuYlUT8gOLqsYEr65gwVItnW0EKaEyznTPoVi4ct5
CW/GPlbgu7Kj/1jXR83ijHHI9Gw9Ai9bdMiEv9MOwBrJtTH8z8DbO4FDaiimcJkH
p4KBs2iOiuh+H6kscFBts4uoem2cBmp1ZH3PGut+LmnTotAe9qrHHlW/O4RCAlXi
wwrvDSv6Z+44D4Po9Z7GXEBSMVxNYIOclvv2hA2GhUv3juov5hGdV45/ejsw6jeM
GYvrN+VuDAZ4hSi2XR2I0WOv+CGwKJCYfNHRKrlkxJohipJx2OVyo+NNfFZztZ/q
Vq72DB40hyTK/yt4CVGSIfkeYSrqDQeN1diRbhtTcw==
=21PI
-----END PGP SIGNATURE-----