[MPlayer-dev-eng] documentation policy

[Diego Biurrun]

Jonas Jermann writes:
 > On Sat, Oct 19, 2002 at 03:40:35PM +0200, Arpi wrote:
 > > > Over the past months we have moved from one documentation maintainer
 > > > to a team of documentation maintainers, but I believe we have to take
 > > > this notion one step further.  Gabucino has very little net connection
 > > > atm (IIRC), I am buried in work, studies and whatnot, Jonas is doing a
 > > > great job on the man page, but still the ToDo-list is growing and not
 > > > shrinking.  In short, we need to distribute this on more shoulders.  I
 > > > would therefore like to propose that we start some sort of
 > > > documentation policy.  All developers should aim to keep the docs up
 > > > to date when they add options or modify existing ones.  We could also
 > > disagree
 > > i don't mean i don't agree :) but i know it will not work.
 > > developers don't like, don't have time (and sometimes don't even know)
 > > to write docs.
 > yeah

It does not work at the moment.  The docs are out of date and the ToDo
is growing.  The current system just is not working.  We need to find
a way to improve it and the way is to work together as a team and
distribute the work among more people.  Nobody has the time, but
somebody has to do it.  I'm not asking about tutorials or elaborate
explanations, just a basis to work on.  All the developers know how to
write this and as I said, improving on existing work is no problem.
I'm not trying to force hard rules on people, but working on the
documentation should be considered good karma.

 > > > ask this of people sending in patches and add it to patches.txt.  The
 > > > point is that if XYZ adds some option to MPlayer extending the man
 > > > page by a few lines, this should not take XYZ more than a few minutes
 > > > and be an accurate description.  In contrast, if I (or one of the
 > > > other docs maintainers) try to do this, I will have to RTFS (and
 > > > understand) and maybe also ask google, the mailing lists or on IRC.
 > > why?
 > > when someone send a patch with new options, he describes how does it work
 > > in the main containing the patch.
 > > if some cvs developer adds a new option, he includes short description in
 > > cvslog, or write a longer ANNOUNCE message to the deveng or users maillist.
 > > you should catch them, do rewording, formatting and commit ;)
 > > if you don't understand sth, ask on IRC or ml. you don't have to rtfs.
 > 
 > I agree with Diego. Most time you have to gather all informations and it
 > takes it's time... So, developers please _make_ ANNOUNCE messages that can be
 > used as a base for the man page. Most time it's not the case....

If somebody writes a description for the patch, why not add that
description to the man page?  Shouldn't take more than 5-10 extra
minutes, that's not much to ask for.

Unfortunately ANNOUNCE messages are quite rare and cvslog descriptions
tend to be quite terse.  Take this one as an example:

Modified Files:
	dec_audio.c 
Log Message:
Adding -format and -af switches

This can only be documented by RTFS (or ml/IRC) and this is the rule
rather than the exception.  It's just that more efficient if the
original author adds the original description, it really does not have
to be more than

  -format <file format>
        Converts any movie into your choice of DOC, XLS, PPT file
        formats (XML planned for a future release).

Can we at least try to aim for something like this?

 > > also, it's good if developers sometimes review the manpage, at least reading
 > > the cvslog, and notify the doc team if something was misuderstood or wrong.
 > yeah

Of course.

Diego