[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [pygame] Using reStructuredText for document sources



On Fri, Mar 4, 2011 at 12:52 PM, René Dudfield <renesd@xxxxxxxxx> wrote:
 
Hi,
 
oops.  I was supposed to go through and fix the documentation for the 1.9.2 release.  There's hundreds of comments, and it took me about a week of writing last time I did it.  I didn't see myself having a week for doc writing before the last release, so we decided it would be done in the 1.9.2 release.
 
 
Well, I'm sure I speak for everyone when I say what we understand, and we appreciate your generousity with your volunteer time.
 
 
For lots of the comments, they're not obvious easy ones like "You wrote 'blua' there, I think you meant 'blue'.  The more common ones are misunderstandings.  So for those you try and figure out why they could not understand it and rewrite the comment.  Or they can even be bug reports in there too.
 
 
One of the cool things about a wiki is that even the misunderstandings contribute.  When someone misunderstands something, and "corrects" it incorrectly, it illustrates an opportunity for improving the clarity of the documentation.  Then, when someone else (or the same person, later, as in the case of Mr. Anonymous 2007 for the blit method) corrects the erroneous correction, he can adjust the prose to make it clearer, to prevent such misunderstandings in the future.
 
I know that when I write code, it is inevitable that some of what seems perfectly obvious and clear to me at the time is anything but obvious, even to me, a year later.  The implementer is probably the person most qualified to write accurate documentation, but he might be the person least qualified to write clear documentation.
 
I am planning on going through the comments again - very soon.  The process I take is to address any comments I can, and delete them if I've covered them.
 
I'm going to improve the comment system on the website to improve the work flow.  To add the ability to mark a comment as 'dealt with', or 'example'.  So when going through them, the options are 'delete', 'dealt with' or ignore for later.
 
I really love the idea of people being able to edit the documentation online.  Then when they save the form, it would send a patch (or pull request).  I think that would be ACE, and also super RAD.  Sort of like a wiki that integrates with our svn.  I guess if it just lists the patches online, then anyone who wants can review them and apply to svn.
 
 
That sounds cool!
 
Uh, what does "ACE" mean?
 
Dave
 
 
 
 
cya!
 
 
 
 
 
On Fri, Mar 4, 2011 at 5:41 PM, Lenard Lindstrom <len-l@xxxxxxxxx> wrote:
 
Hi,
 
I guess the concern is that there is no one assigned with doing overall maintenance of the documentation. Pygame is an informal operation.
 
Lenard
 
 
On 03/03/11 11:28 PM, David Burton wrote:
 
Here's a better example, from the same documentation page, a correction submitted nearly two years ago, still uncorrected in the formal docs:
*Surface.unmap_rgb*
/convert a mapped integer color value into a Color/
Surface.map_rgb(mapped_int): return Color
*May 27, 2009 2:45am - Anonymous*
Also, it should maybe be noted that it returns 4 tuple items, not just 3.
My guess is RGBA tuple instead of RGB, but I'm not an expert :P
 
*May 27, 2009 2:43am - Anonymous*
convert a mapped integer color value into a Color
Surface.map_rgb(mapped_int): return Color
       ^
Shouldn't it be "Surface.unmap_rgb"?
 
 
 
On Fri, Mar 4, 2011 at 2:17 AM, David Burton <ncdave4life@xxxxxxxxx <mailto:ncdave4life@xxxxxxxxx>> wrote:
 
   */Oops!/*   I was obviously too hastly picking my example.