[gst-devel] API reference updating for 0.9 -- your help needed!

[Andy Wingo]

Hey all,

On Friday we tried to work on getting the API reference documentation in
a respectable condition. Thomas, Wim, Julien, Stefan, Edward, Mike, and
I chose different files and went through them. This was coordinated via
a wiki page [0].

We focused on consistency, correctness, and readability. We fixed easy
things and wrote down some notes for future fixes, although these notes
are not online atm. There were some teething problems, but we eventually
settled on a common style [1].

[0] http://live.gnome.org/GStreamerDocsTriage
[1] http://cvs.freedesktop.org/gstreamer/gstreamer/docs/README?r1=1.16&r2=1.14

So we got through a few files. It went slowly at first but the next time
that we do it it will go faster. The problem is, there are about 140
files that we need to review, and 4 weeks in which to do it. If each
file optimistically takes half an hour, that is about *3 hours per week
per hacker* that each person needs to spend on the docs.

This is then a call for help! How, you say? Why it's quite simple:
  * All of the people mentioned above should continue to work on docs 
    on a weekly basis.
  * Anyone else who understands what the docs should say is MORALLY 
    OBLIGATED to help out.
  * Anyone else with CVS commit access but who does not feel
    comfortable reviewing content can help out greatly by making the
    existing docs more consistent. For example, change this:
      * @pad: the #GstPad to stop the task of
    to:
      * @pad: a #GstPad
    and the other guidelines listed in [1].
  * Those without CVS commit access can comment on the "Description" 
    sections of the API docs at [2], which we will keep up-to-date,
    filing bugs if the sections are not clear or incorrect, preferably
    with rewordings.

[2] http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/

D'accord?
-- 
Andy Wingo
http://wingolog.org/