<html><head><style type='text/css'>p { margin: 0; }</style></head><body><div style='font-family: arial,helvetica,sans-serif; font-size: 12pt; color: #000000'>Pete,<div><br></div><div>Is there a way I can help contribute with the docs project again? Possibly something small to start with or I can work on the guide I was working on. </div><div><br></div><div>- Chris Roberts<br><br><hr id="zwchr"><div style="color:#000;font-weight:normal;font-style:normal;text-decoration:none;font-family:Helvetica,Arial,sans-serif;font-size:12pt;"><b>From: </b>"Pete Travis" <me@petetravis.com><br><b>To: </b>"For participants of the Documentation Project" <docs@lists.fedoraproject.org><br><b>Sent: </b>Monday, November 11, 2013 6:51:06 PM<br><b>Subject: </b>Lowering the participation barrier for Fedora Docs<br><br>I took some time over the weekend to update my workstation to F20. It<br>involved performing a lot of now routine tasks; installing the package<br>set I use, pulling in the git repo I keep for $HOME, updating /etc/fstab<br>to include network shares, adding a couple polkit rules for libvirt,<br>blah blah. I'm sure we all have such a list.<br><br>These are among many routine, everyday tasks for Fedora users. The kind<br>of task that an experienced user could sit down and perform, and write<br>up a how-to for the action on the fly while they do it. The kind of task<br>that an inexperienced user would ask about on a forum, or on irc, or<br>research with relatively specific search terms. I think of this as<br>'incidental' or 'case-specific' documentation, rather than generalized<br>documentation as provided in the guides.<br><br>Our existing documentation base is *great*, and anyone who reads through<br>it all will surely come out with the ability to fill in the gaps and<br>handle case-specific problems. We're teaching techniques and tools, not<br>execution. However, between the broad nature of the guides and the SEO<br>reality of a publican site, I think we are failing to reach many users<br>that are actively looking for tutorial-format content.<br><br>Publican based guides have one major shortcoming. The barrier to entry<br>for potential contributors is high. I had a chance at Flock to have<br>some candid conversation over beer with a few folks outside of the loyal<br>Docs team, and there was a general consensus that while they might be<br>willing to write some *incidental* documentation - again, my term -<br>contributing to a guide was an ordeal they didn't have time for. We've<br>seen this repeatedly with new contributors as well, people who start out<br>with enthusiasm that fades when there isn't work that they can easily<br>drop into. Contributing to a guide is *not* a casual endeavor; it<br>requires us to not only learn docbook and the subject matter, but to be<br>entirely self-motivated while working on a project owned by someone<br>else. Fitting into the workflow is just as intimidating as learning the<br>tools, if not more.<br><br>I would like to try something different. We should have a product that<br>leverages the experience and quality of our seasoned contributors and<br>enables new contributors to get started. We should have something that<br>helps inexperienced, impatient users. We should enable the Fedora<br>community at large to participate in our efforts, and I think that means<br>coming to them as much as them coming to us. If we have something<br>easier to contribute to, more contributors will likely follow, and then<br>contributors and content for guides as well.<br><br>I've set up a quick demonstration[1] of some software that I think will<br>address these concerns, a python application called "Nikola"[2]. I have<br>a package review in progress for it, and have already packaged some<br>dependencies. Briefly, it takes plain text files with ReStructuredText<br>or Markdown and transforms them into fully themed static websites. It<br>hooks in to transifex nicely as well. Take a look, you'll find a post<br>detailing how the implementation might work, and a post for the kind of<br>content I envision putting there.<br><br>[1] http://appliance.randomuser.org/solutions/<br>[2] http://www.getnikola.com/<br><br>-- <br>-- Pete Travis<br> - Fedora Docs Project Leader<br> - 'randomuser' on freenode<br> - immanetize@fedoraproject.org<br><br><br><br>-- <br>docs mailing list<br>docs@lists.fedoraproject.org<br>To unsubscribe:<br>https://admin.fedoraproject.org/mailman/listinfo/docs</div><br></div></div></body>
<br><br></html>