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

[Jesús Franco]

El Thu, 20 Jan 2011 17:56:23 -0500, Christopher Antila escribió:

> Hello Jesus and everybody:
> 
> I encourage the creation of this "crash course" document. Even though
> I've written a Guide and continue to update it periodically, I forget
> how to use the Docs tools, and I certainly remember how intimidating it
> was when I first started.

Thank you Christopher for your encouraging words. It's really important 
to me for continue this effort. But my proposal was not a document or 
guide covering the topics for beginner contributors. It is for a class 
(or two) delivered on IRC as part of the Classroom initiative.

> I also think that we need more people, as you say, to contribute "for
> real to Fedora top-projects." The Guides collectively have many
> opportunities for improvement. It's not that the Guide owners don't know
> about these possible improvements, but that we don't have enough time to
> make all of the possible optimizations between releases. Additional "for
> real" contributors would be a significant advantage.

Yes, the actual number of people able to maintain the guides is certainly 
small (and for sure without the full time they'd like to have to do it), 
so, this course could be a way to attract more people to contribute, and 
making them *able to do that*, not just "willing to do".

> I'm not sure what you're asking, Jesus, but if you propose writing the
> document yourself, then go ahead and get started! If you would like help
> with specific tasks, like to make sure that a particular chapter is
> correct, you can ask for help on this mailing list.

I'd be glad to write the whole guide (as complement to Publican User 
Guide), but maybe i'm the last person with the knowledge necessary to 
commit that, on this list. I've commited just a few minor tasks, (i'm most 
a translator), and maybe my whole knowledge related to DocBook is the 
most basic of HTML and XML.

However, you can count with when i get the knowledge needed, i'll commit 
the task for myself. I've even delivered a first class (in my mother 
language, castilian) for my fellow ambassadors on the basics of our 
ticketing system at latam (Redmine). I'm not shy to share even a little 
amount of knowledge (should i be?). Just i like to get more knowledge to 
do a more valuable contribution.

> As a more general observation, I wonder if a stronger QA ("Quality
> Assurance") process would help with this problem. I know that some
> Guides have QA contacts, but for others Bugzilla simply gives this
> mailing list, and some (like the Musicians' Guide) have no QA contact
> whatsoever. Lack of an active QA process means that, if a contributor
> makes a mistake, it won't be noticed until after release - and that's
> understandably intimidating.

At the first very time the QA process was proposed for guides, one idea 
was something like "peer review" by another Doc contributor, able to read 
the whole guide and making proposal for improvement, in the form of real 
patches, apart from bugs filed against the guide.

My feeling is than QA shouldn't be a bureaucratic blocking for writers to 
commit the actual writing and maintenance of the guide for continuous 
improvement. It should be a way for let less experienced contributors to 
help with the owners of the guides, but we need at least a minimum 
training to do so.

> Christopher.

Thanks again for your comments on this issue.

-- 
Salud, tierra y libertad
Jesús Franco http://identi.ca/tzk
http://fedoraproject.org/wiki/User:Tezcatl