-----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----- -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
