1 |
El 26/08/11 04:45, Matt Turner escribió: |
2 |
> On Thu, Aug 25, 2011 at 1:41 AM, Joshua Saddler <nightmorph@g.o> wrote: |
3 |
>> On Tue, 23 Aug 2011 09:43:51 -0400 |
4 |
>> Matt Turner <mattst88@g.o> wrote: |
5 |
>> |
6 |
>>> On Tue, Aug 23, 2011 at 4:52 AM, Sven Vermeulen <swift@g.o> |
7 |
>>> wrote: |
8 |
>>>> On Mon, Aug 22, 2011 at 08:16:59PM -0400, Matt Turner wrote: |
9 |
>>>>> The information on this page is very irrelevant and confusing to |
10 |
>>>>> me, as a developer. |
11 |
>>>>> |
12 |
>>>>> I don't know how many non-developer documenters we have. I don't |
13 |
>>>>> know what needs to happen to that text itself, but a section |
14 |
>>>>> about how current developers join the documentation team is |
15 |
>>>>> important. Looking at the page, a person must complete the staff |
16 |
>>>>> and doc quizzes. For a developer, it seems that the requirements |
17 |
>>>>> should simply be 1) to have become a developer and 2) completed |
18 |
>>>>> the doc quiz. |
19 |
>>>> Documentation developers are also developers, but they do not |
20 |
>>>> need to be an ebuild-developer. If I look at the GDP current |
21 |
>>>> staffing, there are 8 developers that are also ebuild developers |
22 |
>>>> (or infrastructure or another function within Gentoo) and 11 |
23 |
>>>> developers on the documentation (and translations) only. |
24 |
>>>> |
25 |
>>>> Requiring documentation developers to also take the ebuild and |
26 |
>>>> end quiz would be overshooting, as that is not something they |
27 |
>>>> require. |
28 |
>>>> |
29 |
>>>> Wkr, |
30 |
>>>> Sven Vermeulen |
31 |
>>> Right, I'm saying for people who are already developers, they should |
32 |
>>> really only have to complete the doc quiz. |
33 |
>>> |
34 |
>>> Matt |
35 |
>>> |
36 |
>> You want to contribute ebuilds, you have to go through a process that |
37 |
>> teaches you what you need to know, and shows your mentor that know |
38 |
>> what you're doing; that you're not going to screw up everyone's |
39 |
>> boxes. |
40 |
>> |
41 |
>> You want to write documentation, you have to go through a process |
42 |
>> that teaches you what you need to know, and shows your mentor that |
43 |
>> you know what you're doing; that you're not going to screw up |
44 |
>> everyone's boxes ... *or the Gentoo websites*. (via bad commits that |
45 |
>> break layouts, links, XML, CSS, etc.) |
46 |
>> |
47 |
>> Everyone has to go through a process when wanting to join a team. |
48 |
>> What's so hard about this? Why should ebuild developers get a free |
49 |
>> pass to get write access? Over the years, I've talked with several |
50 |
>> different ebuild team leads, as I was interested in what it took to |
51 |
>> get access to gentoo-x86. There's no free pass for longtime doc |
52 |
>> writers, either, even those that have run their own private overlay |
53 |
>> for a long time. I don't just take the ebuild quiz and get commit |
54 |
>> access. There's a process that I have to go through, too. |
55 |
Yeah but if it is a big nuissance people won't go through it. |
56 |
>> Maybe I'm just reading this wrong, but it sounds like you want to set |
57 |
>> things up so that anyone who wants to change a doc can overwrite it |
58 |
>> directly. That's fine for stuff in /proj/ -- the GDP doesn't care |
59 |
>> about that; documents in /proj/ are solely the responsibility of those |
60 |
>> projects. And that's why, overall, the quality of stuff in /proj/ is |
61 |
>> not as good as what's in /doc/. |
62 |
Maybe that's why proj tends to be more up to date than doc or why we |
63 |
still have the openrc tracker bug open whith many bugs just requiring |
64 |
minor changes to be fixed. |
65 |
> I appear to have touched a nerve. |
66 |
> |
67 |
> Let me revise my previous email. I think an existing (ebuild) |
68 |
> developer should do the following things to join the doc team: |
69 |
> - doc quiz; |
70 |
> - CSS knowledge is a plus; |
71 |
> - have some documentation patches to prove he's not a doofus. |
72 |
> |
73 |
> I don't intend to belittle the doc team, but while your point about |
74 |
> having to go through mentoring for an ebuild developer and therefore |
75 |
> why not also a doc developer is well taken, I have a hard time |
76 |
> believing that there's nearly as much knowledge to take in to become a |
77 |
> documentation developer. Learning GuideXML can be done in a day or |
78 |
> two. Being a good writer is something not easily learned. |
79 |
Gonna rephrase that if you don't mind: |
80 |
I don't intend to belittle the ebuild writers, but while your point about |
81 |
having to go through mentoring for an ebuild developer and therefore |
82 |
why not also a doc developer is well taken, I have a hard time |
83 |
believing that there's nearly as much knowledge to take in to become an |
84 |
ebuild developer. Learning to write ebuilds can be done in a day or |
85 |
two. Being a good writer is something not easily learned. |
86 |
|
87 |
That said I have already written ebuilds which work but... Oh! I'm not a full developer because I have yet to pass the quizzes (which I hope I'll eventually do). |
88 |
|
89 |
> But whatever. I'll just post patches in bug reports. It's not worth |
90 |
> the time to go through a second recruitment process to that I can |
91 |
> modify a couple pieces of documentation about the architecture teams |
92 |
> I'm a member of. Maybe these documents should be under /proj anyway; |
93 |
> they certainly weren't looking very healthy under /doc. |
94 |
That's what I usually do and then have fun seeing them ignored by the |
95 |
package responsibles... For example I'm still waiting for news of the |
96 |
dev-p2p team on an updated linuxdcpp ebuild with some patches I sent in |
97 |
July. |
98 |
|
99 |
So where I'm trying to get? |
100 |
|
101 |
Well turns out both sides have bad practices but whilst one is |
102 |
overpopulated the other one isn't. My opinion is that the best policy |
103 |
would be a segmentated policy (as for example happens with staffer and |
104 |
full developers), and have two types of document writters ones which |
105 |
only do a small test and only correct small thingies, and the ones that |
106 |
do the long test to be able to do major changes and write docs from |
107 |
scratch. Both should be surveilled for some time (basically until the |
108 |
newbie does things properly) by somebody with experience who should tell |
109 |
them what to fix (because yes, at times there is nothing better to avoid |
110 |
mistakes than being shown them). |
111 |
|
112 |
What we'd get from that in the middle term will be a doc team with a |
113 |
large base of small fixers which keep documents up to date and some big |
114 |
guys that will produce new quality documentation. |
115 |
|
116 |
Those are just my 2 cents. |