(re-sending since I didn't get a reply for it)
On Monday 12 September 2011 21:29:12 Carl Trieloff wrote:
> On 09/11/2011 05:16 AM, Doron Fediuck wrote:
> > On Sunday 11 September 2011 12:11:27 Itamar Heim wrote:
> >> Cc'ing some existing leads for comments
<SNIP>
> > 0. Title is missing. I'm guessing it's the same as document name?
> >
> > 1. There's a combined usage of 'project' and 'sub-project'. I suggest using 'project' to simplify it.
> > If you take Apache for example, they host projects, and even real sub-projects (http://db.apache.org/derby/derby_proposal.html)
> > they end up being listed as projects (http://projects.apache.org/indexes/alpha.html#D).
>
> done
>
> > 2. The following needs some re-phrasing:
> >
> > IT is expected however that if you have contributed doc, and are not an expect on code that you
> > don’t ack patches for example. You can also be voted into one sub-project and not another based
> > on your area of influence, or you could get into them all.
> >
> > * IT => It
> > * doc => a document?
> > * and are not an expect => and are not an expert?
> > - Generally this paragraph begins with one thing, and ends with something completely different.
> > I'd think of adding each sentence to a relevant paragraph carrying the same theme / subject.
>
> re-worked, see what you think. (go ahead and edit it directly if needed.)
>
> >
> > 3. There are terms that need clarification, or typos. For example: wsdm. Is it VDSM? Something else?
>
> fixed
>
> >
> > 4. And probably the most important. This document is _also_ about being a maintainer. But it's
> > _also_ about being a (sub-)project contributer (and maybe some more also's);
> >
> > - Contributing to a sub-project
> > - Adding to the discussions and contributing code
> > and there's more contents about giving to the community. This is all relevant
> > to project / community membership.
> >
> > => This document should be spitted into community membership document and
> > (sub-)project maintenance. Currently it's a mix of both.
> >
>
>
> Don't we want it mixed? why would we draw a line between the two roles?
> having people thinking of community and code together is healthy.
>
> Carl.
>
OK, looks much better now.
Some final (I hope) remarks;
1. We now have 2 "Becoming a maintainer" headers. I'd change the 2nd one to
something like "Applying for a project maintainer role" or anything alike.
2. WRT contribution and maintenance mixture, it takes the focus off the
document's topic, for no visible reason. I'll try to explain with 2 examples;
a. The car
You just bought a new car, and you look into the owner manual, looking
for a quick & simple way to adjust your radio pre-set stations.
You get the information in one chapter which includes the complete wiring
scheme, board design and explanation on connector types to use when connecting
to amplifiers or phone car-kit. Will you think it's very helpful and easy to
understand how you should set your radio buttons?
Now think of the mechanic guy in the garage, getting the same manual,
which he's supposed to use in order to verify what is short-circuiting
the car embedded media controller. What will he think when he needs to
read the connector description along with setting radio buttons?
Is mixing all the information a good idea? Does it help both guys? Any
of them?
b. Git Book
http://book.git-scm.com/
As you can see there are separate chapters for each type of user;
Basic, Intermediate and Advanced.
I'm sure someone who looks for a way to recover corrupted objects,
won't find git clone syntax very helpful while he looks for the relevant
information.
3. Now back to us...
I think the following should be used in a different document;
- Contributing to a project
- Adding to the discussions and contributing code
- Large projects
These (and maybe some more) should be located in a document
focused on general community contribution and oVirt project
specific contribution rules / policy / code / coding-conventions,
etc. Apache,for instance, asks every contributer to sign something
making the code contribution owned by / used by the relevant
project, so there are no license / rights issues. This could
be a good place for explaining such a signature, should we
require one.
Current document should be lean and mean; Containing the relevant
information on becoming a maintainer, responsibilities, ethics,
policies, etc. The document should start by referring to the
project contribution document. In this way you give more
background if needed.
--
/d
"All computers wait at the same speed."