Lowering the participation barrier for Fedora Docs

[Eric H. Christensen]

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

On Mon, Nov 11, 2013 at 04:51:06PM -0700, Pete Travis wrote:
> I've set up a quick demonstration[1] of some software that I think will
> address these concerns, a python application called "Nikola"[2]. I have
> a package review in progress for it, and have already packaged some
> dependencies. Briefly, it takes plain text files with ReStructuredText
> or Markdown and transforms them into fully themed static websites. It
> hooks in to transifex nicely as well. Take a look, you'll find a post
> detailing how the implementation might work, and a post for the kind of
> content I envision putting there.

I've not been able to fully look into your proposed solution but I wonder if we're not doing a good enough job in making DocBook XML easy.  I've found that I will, at the drop of a hat, create a Publican article and start writing things up because it's just easier to output the bits in a sane way.  I've tried to use other Markups including ASCIIdoc[tor] and I've not found another solution that's as flexible.

What happens to all the existing source that we have in DocBook XML?  If we start something new can we move our existing code over or will we be supporting multiple code source types?  With multiple code source types we'll just end up supporting multiple tools for rendering in the end as we'll never get rid of the old, I suspect.

I also wonder how we'll handle all the different renderings of the guides.  With each guide having four formats and each guide needing to be available for each version of Fedora we will quickly reach a point where it's very difficult to manage all that output.  We've actually been down this road before.  When we were using Publican 1.x we had to hand spin our website which turned out to be a nightmare.  What we see in Publican 2.x is a direct result of 1.x not being scalable.  We know that 2.x is only scalable to a point and thus 3.x solutions (SRPMs) being used to maintain that scalability.  I'd hate to see us venture down this road all over again, relearning from old mistakes... again.

I suspect that it may be better to educate people on why DocBook XML is a good solution and how to easily mark up a document.  It may also be a good idea to figure out how to improve some of our existing documents as some of their structures make it very difficult to find where things are.

- -- 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)

iQGcBAEBCgAGBQJSgjiHAAoJEB/kgVGp2CYvSCoL/23FyOcQ3kLVGPaZamanxV5x
krn/KxLFy1Mi7EMCCrRztQOI01jJdWSWZACDrvluDUCOcr1/sr9dNiMn4D7qEt+t
jIqGkZr9QMOarIBelZhSsptpfLpKchE7ogzhfURxZLSyReeDYor6g5g3bDT57orW
K6B1viEJFylRS628RpPK78BNuBDoOyD7ZBVSJFBeBgIurkiuPoVOWzOBHklCPk6b
oenjmyCE23XmuQsh4UH7PGfrDwt5femBT+4acMxq+55PuI67AqG6Fvqukx/48W/0
utIYn+NGW1bINq8UbDPm0+usc0Jqsfk/sMrOO1d3cMQ+OONP9VR64QkR6WtM+oiy
i9xGtjhulR7w9QP3bjrSBXUbzpx20kWZfFP63bq8rMad7+1iQJ6GB7US84M53Gcs
sfpAiDtYl8Weh10K7yeB2ubxStJCwvsZNnP5+89Ey0OJDgp8Dc6CfdLl5KqguhGm
Sd11VHwbmzSKhg0JLv/+sKJFfVHi3nB9v/SOZEWdgQ==
=fR6f
-----END PGP SIGNATURE-----