Please tutor a crash course on Docs Project tools & workflow.

[Jesús Franco]

Hi Docs team.

I've read on last meeting-minutes the action item about getting someone 
to leader the RelNotes writing. There is a lot of talk lately too about 
getting more people into contributing for real to Fedora top-projects.

But i think this is not an area than marketing can manage just by making 
Fedora look friendly and open to all. I've read since i joined to Docs 
project a lot of people (just like me), willing to join, and no matter 
how much is said "don't worry, if you broke something we can fix it"; 
it's simply overwhelming the idea of doing things bad since many times we 
don't know the way of doing things the right way.

We need to learn how to make successfully what we'd like to. And no, there 
is no just matter of time or reading the bunch of pages under Docs 
category in the wiki. You know a lot of there is outdated and it becomes 
confusing when you read an updated page and kindly someone corrects and 
says: "It's outdated". A big WTF. (That's why i don't like mediawiki).

This is happening because we are not the number of qualified people we 
would like to be. But we can.

I'm working on a Draft for an introductory crash course to Docs Project, 
based on practical workshops to learn the basic of Publican, *git*, and 
the workflow preferred by the actual contributors.

The goals of this course, would be:

0) Acquiring practical dominion of that tools, letting more people feel 
confident to join to the Docs project.
1) Recruiting more people to work into real tasks of Docs Project.

Forgive my references to gaming.

World 1 

***Tutorial level. We need for first class...***

* Make a schedule than effectively can let people to commit minor tasks 
with Publican/git, since first class.
* A main tutor able to run at least one-and-a-half hour class on IRC, 
showing folks how to produce their first Doc with the minimum hassle.
* People able to join to gobby writing of the first article of folks, to 
help tutor in fixing mistakes people will fail (something like paired 
programming driver-navigator).

For folks unable to join to classroom session (and who can't finish the 
first world at first attempt).

* More people helping the tutor in helping people (it can be via ML) to 
solve issues they (we) will face for sure at their first attempt.
* Also, people answering questions the students will confront sharing 
their patches, and troubleshooting whatever error they will found.

We can encourage students too, to helping each other via the ML, and 
getting into the thread just for fix minor mistakes.

Following the games analogy:
Level 1 would be actually writing with succes their first DocBook article.
Level 2 uploading to a git repo.
Level 3 taking another people article and suggesting changes via a patch.
Level 4 applying the patch and adding collaborators. (er, optional?)
Level 5 sharing their experience and figuring out what official guide 
they'd like to contribute.

World 2.

This time the challenge would be:

* Choose a Docs top-document (Release Notes is my first candidate) to 
give people the chance to get into the real workflow of Docs project.

We would combine again at least a synchronous session and the heavy load 
could be conducted through ML/bugzilla and work with repos/branches.

I'm not so clear about that, so i'd like you really give feedback to:

https://fedoraproject.org/wiki/Docs_Project/
Course_for_New_Contributors#Second_week.2C_explore_into_the_jungle

==== Too much changes? Naah ====

If you read carefully, we could load a bunch of people into ML and maybe 
messing into bugs and patches (and always has been said that's fine, 
since we always can clean the house, right?); Apart from the classroom 
meetings via IRC/Gobby, we wouldn't take much more work than today. Just 
compare that to the steps to join L10N and Ambassadors teams*.

The real difference is we could arrange by some weeks people learning 
together and working with Guide owners and experimented people, hopefully 
giving them (us) a more solid scale to jump into Docs boat than sending 
them to find the bit into the mess of Docs category in the wiki.

Also, everything of this experience should be stored as an updated 
reference for people unable to join at the first invitation. I'm 
confident than this would be something similar to writing code from 
scratch in a cleaner and fresh way, than trying to fix overbloated code 
with too many patches acumulated over the time.

And i'm pretty sure all that experience could be summarized and rearranged 
as an actual course in a way people could follow the manual and becoming 
more able to join Docs project and getting their hands dirty.

You can fire to me now ;)


Best regards.
--
Jesus Franco
Fedora Ambassador and Translator
http://fedoraproject.org/wiki/User:Tezcatl

P.S. I don't say translators and Ambassadors can't become better and rich 
higher levels in the quality of our contributions (I don't believe in 
number of strings translated just because Google seems easier than 
actually checking our translations). Just than those teams don't look so 
intimidating and it's lot of easier growing into them step by step.