| 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. |
Archives