On Fri, Mar 4, 2011 at 12:52 PM, René Dudfield <ren...@gmail.com> 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 <le...@telus.net> 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 <ncdave4l...@gmail.com<mailto: >>> ncdave4l...@gmail.com>> wrote: >>> >>> */Oops!/* I was obviously too hastly picking my example. >>> >>> >>> >>
