[prev in list] [next in list] [prev in thread] [next in thread]
List: fedora-docs-list
Subject: Re: Lowering the participation barrier for Fedora Docs
From: "Chris A. Roberts" <croberts () cintrixhosting ! com>
Date: 2013-12-30 21:45:11
Message-ID: 1e583838-4d6d-48c7-9ce5-c19f7705fe3c () zms-001-sfo ! themessagecenter ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
Pete,
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.
- Chris Roberts
----- Original Message -----
From: "Pete Travis" <me@petetravis.com>
To: "For participants of the Documentation Project" <docs@lists.fedoraproject.org>
Sent: Monday, November 11, 2013 6:51:06 PM
Subject: Lowering the participation barrier for Fedora Docs
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/
--
-- Pete Travis
- Fedora Docs Project Leader
- 'randomuser' on freenode
- immanetize@fedoraproject.org
--
docs mailing list
docs@lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
[Attachment #5 (text/html)]
<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>
[Attachment #6 (text/plain)]
--
docs mailing list
docs@lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic