Lowering the participation barrier for Fedora Docs

[Kevin Glazenburg]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I fully agree with the fact that the current workflow is really hard
to get into, even if I had loads of time to learn it, without simple
tasks to start with, I doubt I will ever learn how the workflow for
this group works.

Kind Regards,
Kevin Glazenburg

On 11/12/2013 12:51 AM, Pete Travis wrote:
> I took some time over the weekend to update my workstation to F20.
> It involved performing a lot of now routine tasks; installing the
> package set I use, pulling in the git repo I keep for $HOME,
> updating /etc/fstab to include network shares, adding a couple
> polkit rules for libvirt, blah blah. I'm sure we all have such a
> list.
> 
> These are among many routine, everyday tasks for Fedora users.  The
> kind of task that an experienced user could sit down and perform,
> and write up a how-to for the action on the fly while they do it.
> The kind of task that an inexperienced user would ask about on a
> forum, or on irc, or research with relatively specific search
> terms.  I think of this as 'incidental' or 'case-specific'
> documentation, rather than generalized documentation as provided in
> the guides.
> 
> Our existing documentation base is *great*, and anyone who reads
> through it all will surely come out with the ability to fill in the
> gaps and handle case-specific problems.  We're teaching techniques
> and tools, not execution. However, between the broad nature of the
> guides and the SEO reality of a publican site, I think we are
> failing to reach many users that are actively looking for
> tutorial-format content.
> 
> Publican based guides have one major shortcoming. The barrier to
> entry for potential contributors is high.  I had a chance at Flock
> to have some candid conversation over beer with a few folks outside
> of the loyal Docs team, and there was a general consensus that
> while they might be willing to write some *incidental*
> documentation - again, my term - contributing to a guide was an
> ordeal they didn't have time for. We've seen this repeatedly with
> new contributors as well, people who start out with enthusiasm that
> fades when there isn't work that they can easily drop into.
> Contributing to a guide is *not* a casual endeavor; it requires us
> to not only learn docbook and the subject matter, but to be 
> entirely self-motivated while working on a project owned by
> someone else. Fitting into the workflow is just as intimidating as
> learning the tools, if not more.
> 
> I would like to try something different.  We should have a product
> that leverages the experience and quality of our seasoned
> contributors and enables new contributors to get started.  We
> should have something that helps inexperienced, impatient users.
> We should enable the Fedora community at large to participate in
> our efforts, and I think that means coming to them as much as them
> coming to us.  If we have something easier to contribute to, more
> contributors will likely follow, and then contributors and content
> for guides as well.
> 
> 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.
> 
> [1] http://appliance.randomuser.org/solutions/ [2]
> http://www.getnikola.com/
> 
> 
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.15 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBAgAGBQJSgg3WAAoJEBX9Y7Nh3T/hBxAP/1mhFyGtvDThXRjFvTxe8MBs
A3Y0GFT618hqcRTWhL3A2DULX6bPeSgAvGzihqh1rGPZPhSz+1xr5vT86vDKHBm8
ft74Rsy2fVQEvG0CkIZheBNljsLgpzXFbdfzTh7EdNgiAfscLcqAHh6A+JKxhjvf
w1OvhE083NjLRH9j1nMc1gz8cjnpOk1ACfKm4xGpjUPZEeNu/62w0bYDO01oDOd/
Tks6EOAEhWzX75ssTZWjHXDx7PazKjMeNomLieVNB8AzwwWzL3ErSyGZVEtVrBWv
TLQ0hhU625FfZtlJNUALOby69DwehLbQQWB0rHWlLcaRHZ2SLZ6wRFgMcS0jgwn1
gMtqVmLhlFUSgGPWh3UanKKWHaGDW0JhDrqERAiktt1Cmvl6fsEQwY9+FdJlGmng
JEqpTaAQxRx8UvKp9vcBziVU+jhQ6Q/iFo7QB54QuuFVjll3escHEQhRT4jnK6si
u1us1RF4TGnw5VySSZ3VisBZfv/yXkvT80wKZe8jfk8SDmzjld8yyFPhE14FyxOE
4AyMx5er5n3m0Cu7877uOIxN5uBCeYQloSQ+V7c4f/LrMp08KcEaTjpxydmRxMVy
5tiwom51+T2v43tKgt1w9SbL8jCnUtUU/lIsr5pdg9Rr6ypw07Cvm8mmdB2uFbG7
Zo0Q60zlm3tAB/0sRX6z
=6v6z
-----END PGP SIGNATURE-----