who and when and how to write documentation (was: Re: [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)

[Diego Biurrun]

On Wed, Apr 26, 2006 at 03:36:54PM +0200, Alban Bedel wrote:
> On Wed, 26 Apr 2006 02:25:15 +0200
> Diego Biurrun <diego at biurrun.de> wrote:
> 
> I know this and have big respect for it. Playing the english teacher is
> probably not much fun.

I don't complain and it does seem to pay off to an extent, everyone's
English has improved over the years...

> > Also, don't forget that the code devs outnumber the docs devs 10:1 and
> > fixing everybody else's basic spelling/grammar mistakes is a lot of work
> > and not a terribly sexy thing to do...
> 
> That's true, althought there doesn't seems to be much work going on with
> the docs. I might be mistaking as i don't see the commits, but for one
> thing i know that the OSD menu section still hadn't seen a single update.

I'd say you are mistaken.  Over the last year or so the MEncoder docs
have undergone a major rewrite, encoding-guide.xml is a 170k file!  The
man page has gone from rev 1.943 to 1.1269, growing from 217k to 249k.
The rest of the XML docs has not seen that much development, but it also
hasn't been static.  All slave mode commands have been documented, all
keys and other interactive controls.  Now finally all options are
actually described in the man page and I have added (preliminary)
documentation for environment variables that we support.

> It still state "the Preferences menu is currently UNIMPLEMENTED!" althought
> i implemented it for quiet sometimes now (and mentioned that on irc
> several times).

I probably overlooked that commit, there are so many...

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

Sure you miss those times, you did not have to write any docs back
then..  Hey, I also miss the times when my mom used to wash my clothes
when I was a kid... ;-)

> PS: No i'm not trying to argue that the devs should stop writing any docs.
>     Just that the doc ppl should do a bit more effort, and sometimes
>     instead of just flaming for poor/missing docs also get the dammn
>     job done.

I think you are confusing flaming with reviews.  It's often more work
for me to point out mistakes instead of quickly fixing them myself.  I
still choose to point them out in order to improve things in the long
run.

First off I'd like to mention that the discussion started out with
doxygen comments.  This is code-level documentation, not end-user
documentation like a man page.  I don't think anybody but the author of
the code itself should write it.  Well, other people *could* write it,
but it may take them very long to understand the code in the first
place, while the author can possibly create it in one tenth of the time.

Yes, it's true, (way back) in the past devs would not write user-level
documentation at all and the docs team would take care of that.  While
this is of course comfortable for the coders this strategy has a series
of serious drawbacks.

The most important is that it just does not scale.

Look at how many people have been granted CVS access over the last year
and how many of them are documenters.  At the same time the documenters
have less and not more time than in the past.  So it's not a matter of
who writes the documentation but whether it gets written at all.

Then there is the problem of domain knowledge.  To properly document
some new code you need to understand it in the first place.  Are you
familiar with all the different parts of MPlayer, say, the filter
system?  You aren't and the same goes for all the documenters.  Docs
people tend to be less and not more technical than the others.  But
while coders tend to work in more or less small corners, documenters
need to look after everything.  So they basically have to know about as
much as all the coders combined.  For obvious reasons, this cannot work.

Notice that nowadays the documentation is more complete and up-to-date
than ever.  I'll go on the record for saying that this is largely my
accomplishment.  Not necessarily because I wrote it all (I did
contribute no small part, though) but because I've thought long and
hard about which processes might work and which don't.

My conclusion is that documentation has to be a team job if you want to
see it done well or even at all.  At least in the situation where we are
in where coders outnumber documenters more than 10:1 by numbers and
probably even more by available time.

Also note that if I want to document $feature that you have just
committed, I'll probably have to ask you to explain some or all of it.
You will do that by writing something in a mail or on IRC.  Writing
something similar into the docs yourself is probably not more work at
all.

If you think that I write less docs than I used to then the answer is
that it's true.  I've discussed this with Arpi way back: Once you start
being a maintainer and review other people's stuff, you end up writing
much less code/docs yourself.  Nevertheless it's an important job that
needs to be done.  Unfortunately most people are very lazy about this.
You can count the number of active reviewers with the fingers of one
hand...

Furthermore I do (too) many other things apart from documentation
nowadays.  I also work on FFmpeg, the build system, the homepage,
mphq1/2 and I have less time than I used to.  So I prioritize things and
do the things I enjoy more first and also those that I consider more
important.  Incidentally I consider reviews more important than original
work, because I think it pays off in the long run and reviewing is
neglected so much.

This came out much longer than I had originally planned, but hey, even
if I did not convince you (which I do hope I did), I guess you'll
understand me better now...

Diego