1 |
On Wed, 28 Nov 2007 13:14:05 -0800 |
2 |
Donnie Berkholz <dberkholz@g.o> wrote: |
3 |
> Many of the replies keep asking for details -- details that don't |
4 |
> exist. Apply the concept abstractly: things that need to be |
5 |
> documented must have documentation available in the appropriate form |
6 |
> at the time they're committed. |
7 |
|
8 |
Which still doesn't bring anything discussable or implementable. A |
9 |
large part of why many things aren't documented is that people have |
10 |
very different ideas about what level of documentation is required; |
11 |
this does nothing to affect that. |
12 |
|
13 |
> What remains unclear about this principle? |
14 |
|
15 |
It's entirely nebulous and has nothing that can be discussed or agreed |
16 |
upon, beyond giving people a feel good "ooh, yes, we should do this" |
17 |
with no practical purpose. It has an unpleasant smell of something a |
18 |
Dilbert-esque manager would introduce after having read a "Project |
19 |
Management for Dummies" book full of slogans and generalities. |
20 |
|
21 |
So, if you want to take this somewhere useful: |
22 |
|
23 |
* Decide what the scope of a change is. Are we talking anything |
24 |
user-visible? Anything substantially user-visible? Anything requiring |
25 |
user action? Anything developer-visible? Anything requiring developer |
26 |
action? Anything visible to small numbers of developers working in a |
27 |
specific area? |
28 |
|
29 |
* Decide what the appropriate level of documentation is. |
30 |
|
31 |
* Discuss how you're going to get documentation of a sufficiently high |
32 |
quality. Most developers aren't going to go out and spend several months |
33 |
studying technical writing... |
34 |
|
35 |
* Decide whether it's worth putting the limited available writing |
36 |
resources into developer documentation that will only be read by a few |
37 |
hundred people, rather than putting more focus into user documentation |
38 |
that will be read by pretty much everyone. |
39 |
|
40 |
You know... Practical things, rather than things that make you feel |
41 |
good but go nowhere. |
42 |
|
43 |
-- |
44 |
Ciaran McCreesh |