[sugar] apis at 4%

[David Farning]

On Mon, 2008-09-22 at 17:11 +0200, Marco Pesenti Gritti wrote:
> On Mon, Sep 22, 2008 at 4:42 PM, David Farning <dfarning at sugarlabs.org> wrote:
> > What do you suggest?
> 
> If I understand your explanations correctly, the system already
> support some kind of review workflow... could devs just get involved
> into it?
YES anyone can get involved:)

Create a login
I'll add your permissions
Edit

> > I can go back to filing bugs in the tracker or I can post patches to the
> > mailing list.
> >
> > Generating the initial api documentation has an inherent tension.
> >
> > Nobody knows how to get starting writing the 1250+ blank docstrings in
> > Sugar.  Hence, they have been sitting for empty.
> >
> > Following the theory of 'worse is better' we at least need to stub out
> > the docstrings before others will join in the effort.  The initial
> > quality of the docstring will be embarrassingly low.
> >
> > We can improve bad.  The hard step is ironically going from blank to
> > bad.
> 
> Yeah. I'm not suggesting to block you on very detailed review like I'd
> do if it was code. I just suspect that having a very high level look
> to the stuff which is going in might help to improve quality quite a
> bit without slowing you down too much...
> 
> One way to do it, without blocking you on reviews, would be that we
> have a look to the documentation done so far and we post suggestions
> to the list.
> 

Take a look at http://sugarlabs1.xen.prgmr.com/pydocweb/doc/ .  On the
initial pass, I can tag modified strings 'Need Review'.  Then a dev can
go through looking for technical errors and marking them 'Needs work
(reviewed)'. Then I can commit the strings.

By iterating between Needs editing, Needs Review, and Needs Work.  We
can work independently, while gradually increasing the quality of the
docstrings.

pydoceweb has a nice comment system.  So comments (about the
comments)can be attached to individual docstrings.

thanks
dfarning