[MPlayer-dev-eng] documentation policy

[Jonas Jermann]

On Sat, Oct 19, 2002 at 03:40:35PM +0200, Arpi wrote:
> Hi,
> 
> > 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

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

> 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


Regards
    Jonas