[MPlayer-cvslog] CVS: main m_config.c, 1.15, 1.16 m_config.h, 1.7, 1.8 m_option.c, 1.49, 1.50 m_option.h, 1.14, 1.15 m_property.c, 1.3, 1.4 m_property.h, 1.3, 1.4 m_struct.c, 1.4, 1.5 m_struct.h, 1.3, 1.4

[Corey Hickey]

Alban Bedel wrote:
> To tell the truth my impression is that the current doc team doesn't write
> docs anymore. Instead pressure is put on the dev to have them writting poor
> docs which is then eventually rewrote and/or heavily corrected by the doc
> team. I miss the times where the doc ppl acctually wrote most of the docs
> themself.

The difficulty in doing so is that most of the time it's difficult to 
tell what should be written about some new feature. The process ends up 
being like this:

1. A developer commits something.
2. From zero to several years pass.
3. A documentarian asks, "What's this do?"
4. The developer explains the feature.
5. The documentarian rewrites explanation for the docs.

The drawback in such an approach is that it requires a documentarian to 
notice the commit introduces a new feature and care enough to get an 
explanation from the developer. If a developer writes rudimentary 
documentation in the first place, it's much easier for a documentarian 
to fix it.

1. A developer commits something with rudimentary docs.
2. The documentarians can't abide such grammatical problems, so they 
either fix the errors or provide corrections to the developer.
3. The developer makes corrections if they haven't been made already.

The second approach requires a little bit more work of the developer, 
but it forces the documentarians to do more as well, and the docs benefit.

-Corey