On 05/15/2015 09:32 AM, Sandra McCann wrote:

I promised to summarize my recent experience as a doc newbie and kickstart a barriers to entry thread, so here go’s!


My Contributor Persona

Since it reflects on my experience, here’s my background. I’m new to Linux, Fedora, Docbook, and git.  If I got any newer, I’d still be in the eggshell :-)


I do have XML documentation background so that made DocBook less painful.


A Baseline Example

I started out in the Fedora QA area, mostly because it seemed easier to contribute at the time.  As a QA tester, I could easily find a series of test cases and almost exactly what I needed to do in each case to get pass or fail on the test.  These tests started out quite simple (download the ISO and verify the size) and there were enough basic tests that I could keep busy, mark things as passed, or in the rare occassion, log a bug.  (NOTE - logging the bug was only easy because it was a variation of an existing bug so I could just clone and edit).


The parts of this experience that I think helped keep me involved and motivated:

  • starting bar was very low and simple, with instructions.

  • contribution time could be as limited as 30 minutes and I’d have a couple of tests done.

  • If I started something but couldn’t finish, I wasn’t holding anyone up (completely independent tasks).

  • Ability to check something off as done on the test results wiki, get some badges (yes, I’m that easily motivated :-)  

  • A surprise callout thanks at the end of the project that listed ..erm… I think the number of tests done.  Imagine a simplified leaderboard approach.

  • Could build up my experience (ability to run more advanced tests) at my own pace, while still contributing on the tests I already knew how to run. And obvious progression path existed.

  • No real commitment - I just pop in when I can, run a few tests, feel good, go back to the day job. I know I’m not the only one running the tests, so if I can’t contribute for a test cycle or three, I’m not holding anything up.


My Fedora Docs Experience

Now we get to my shift over to docs. I poked at the doc project wiki, and while the front page seems quite clear, I stumbled off and on after that. I lurked a bit in irc, then eventually introduced myself and got a few pointers on what to learn (pointers to a git tutorial and docbook etc).  I floated around for some time after that and didn’t really get involved until someone mentioned the virtualization getting started guide needed work.  Since I was new to Fedora and all things Linux, I didn’t feel confident to volunteer prior to this, but I’m having to write about VMs in the day job so this seemed a good logical extension (aka something I knew a little bit about).  After that, it was fits and starts and fubars with git (some quite recent :-).  I think I’ve got it down now, but time will tell!


Fedora Docs Barriers to Entry

After that long-winded tale, here’s what I think the barriers are, at least for someone with my experience:

  • No simple way to come in, give an hour or two, and disappear for a month.

  • “mentorship’ requires a live person and can be difficult to connect to when first starting out.

  • Steep learning curve for git and/or DocBook if you don’t have prior knowledge.

  • Must have technical knowledge of the subject matter.

  • Confusing set of information on the doc projects wiki*


For the doc projects wiki - I found different paths through it, whether I was starting from the main docs project page, or googling for information and landing on some random page.  I also didn’t find out about the fedorapeople site until grundblom started using it (my fellow traveller on the doc newbie path in the virtualization getting started guide).  


I will also say it helped very much to have another new doc contributor with me along the way.


Anyway, that’s my tale for today!


Sandra



Sandra, that was spectacular well written document. Thank you for the hard work that went into that.

I came to the Docs part of Fedora to give myself projects to learn Linux and give back to the community. So, everything is completely new to me so I am overcoming barriers that most experienced people have already dealt with and are not the Fedora group's issues. (I doubt I am the kind of person Fedora targets to contribute, but tolerates me because of my intentions).

So, my main issue is that I multitask a lot, and focusing on a single thing is hard for me (disk recovery here, new server coming online over there, user just accidentally deleted XYZ, user removed Java and now their crashplan install hasn't backed up anything for two months and they need a restore...) so its really hard to focus. The Fedora pages are information packed and very text dense, which makes it hard for me to process them while multitasking.

For me, information presented in almost billboard format helps me the most (like this): http://research.cs.wisc.edu/htcondor/CondorWeek2012/presentations/thain-dynamic-slots.pdf

And, yes I am going to blame my hardships on focusing on my multitasking, not just getting older....

Otherwise my ability to contribute has been entirely from the assistance Pete and the docs team have provided me in #fedora-docs.

Hope that helps,
-Glen