1 |
Joshua Saddler wrote: |
2 |
> On Sat, 3 Oct 2009 20:45:21 +0300 Markos Chandras |
3 |
> <hwoarang@g.o> wrote: |
4 |
> |
5 |
>> This is actually true. Maybe all devs should have access on docs |
6 |
>> since the docs teams are dead. I would suggest to let all |
7 |
>> developers contribute to documentation whether they belong to docs |
8 |
>> team or not |
9 |
> |
10 |
> No. Many (most?) devs do not write good documentation. |
11 |
> <snip> |
12 |
> They don't know all the myriad documents that need editing to |
13 |
> pick up the change made to one part of a different document. |
14 |
> |
15 |
|
16 |
They say that the enemy of the great is the good, but I think that in |
17 |
this case the enemy of the good is the great. Since many devs can't |
18 |
write excellent documentation the argument is that they shouldn't be |
19 |
permitted to write any documentation. |
20 |
|
21 |
The problem with this is that some of our official documentation is just |
22 |
outright wrong. Right now if somebody follows the docs they are |
23 |
guaranteed to end up with a non-functional system. Suppose a dev edits |
24 |
those docs and fixes the version but doesn't completely clean up the |
25 |
accompanying text or misses some obscure cross-reference. Well, maybe |
26 |
now a user has a 50% chance of getting it wrong - which is better than a |
27 |
100% chance of getting it wrong. Others can then clean it up (such as |
28 |
the folks on the forums who get all kinds of feedback about these sorts |
29 |
of issues). |
30 |
|
31 |
I'd be the first to agree that it would be better to just file a bug and |
32 |
let the doc team clean up the docs. Perhaps this situation is just an |
33 |
anomoly, in which case we shouldn't be changing overall policy as a |
34 |
result. However, if we have a resource bottleneck here then we need to |
35 |
do something to help clear it up. That isn't meant to reflect poorly on |
36 |
anybody who is contributing to docs - you might be doing a wonderful job |
37 |
but unless we can find more of you then you're going to be playing |
38 |
whack-a-mole. |
39 |
|
40 |
The amd64 team ran into a similar issue which is why there is a policy |
41 |
that package maintainers are trusted to stabilize their own packages as |
42 |
long as they've tested them on the platform. That doesn't mean that |
43 |
there aren't decent amd64 team members - only that there simply aren't |
44 |
enough of us to keep up with everything. |