1 |
On 21:33 Wed 28 Nov , Ciaran McCreesh wrote: |
2 |
> On Wed, 28 Nov 2007 13:14:05 -0800 |
3 |
> > What remains unclear about this principle? |
4 |
> |
5 |
> It's entirely nebulous and has nothing that can be discussed or agreed |
6 |
> upon, beyond giving people a feel good "ooh, yes, we should do this" |
7 |
> with no practical purpose. It has an unpleasant smell of something a |
8 |
> Dilbert-esque manager would introduce after having read a "Project |
9 |
> Management for Dummies" book full of slogans and generalities. |
10 |
> |
11 |
> So, if you want to take this somewhere useful: |
12 |
> |
13 |
> * Decide what the scope of a change is. Are we talking anything |
14 |
> user-visible? Anything substantially user-visible? Anything requiring |
15 |
> user action? Anything developer-visible? Anything requiring developer |
16 |
> action? Anything visible to small numbers of developers working in a |
17 |
> specific area? |
18 |
> |
19 |
> * Decide what the appropriate level of documentation is. |
20 |
> |
21 |
> * Discuss how you're going to get documentation of a sufficiently high |
22 |
> quality. Most developers aren't going to go out and spend several months |
23 |
> studying technical writing... |
24 |
> |
25 |
> * Decide whether it's worth putting the limited available writing |
26 |
> resources into developer documentation that will only be read by a few |
27 |
> hundred people, rather than putting more focus into user documentation |
28 |
> that will be read by pretty much everyone. |
29 |
|
30 |
I think that in most cases it is self-evident to the developer how much |
31 |
documentation is useful, and if the community disagrees with that |
32 |
developer, anyone else is welcome to say so. There are always a few |
33 |
people out on the edge, but most people realize how much documentation |
34 |
should exist. I don't see a benefit to all these precise specifications. |
35 |
|
36 |
Thanks, |
37 |
Donnie |
38 |
-- |
39 |
gentoo-dev@g.o mailing list |