RE: [PHP-GTK] what is going on with gtk.php.net?

Rhys: we already _have_ a centrally managed effort.. > -----Original Message----- > From: Rhys Campbell [mailto:rhys.campbell@da-systems.co.uk] > Sent: 16 July 2004 13:07 > To: PHP-GTK Mailing List (E-mail) > Subject: RE: [PHP-GTK] what is going on with gtk.php.net? > > > OK, seems like not many people are with me on this. The ants > anology is good, but like ants I think people will tend to leave > the not so sweet parts. Anyway this post has generated a lot of > traffic so there's obviously a lot of interest in the issue. I > think the idea of a cenrally managed effort is a good one, but > you may be right about it not getting used. Bit sad really as you > can see the good Sun have done on the documentation for Java (a > rival of PHP-GTK????). I'll start thinking about what I can do > this weekend and stop pestering this list with my rantings. > > Regards, > Rhys > > -----Original Message----- > From: Steph [mailto:steph@zend.com] > Sent: 16 July 2004 12:23 > To: Rhys Campbell; PHP-GTK Mailing List (E-mail) > Subject: RE: [PHP-GTK] what is going on with gtk.php.net? > > > > Obviously I'm not saying throw away the present manual there is a > > lot of useful information there. But the old saying goes "Too > > many cooks spoil the broth.". What I'm saying is that central > > management of the documentation is needed to be effective, i.e. > > you look at this widget and document all \ or many of its > > properties, methods ect according to these guidlines \ standards, > > formal methods, or whatever. This work could then be submitted to > > a project leader(s) for review which would then be passed back > > for corrections or included into the manual. I'm sure, like > > myself, many have busy lives but if we work with common aims on > > this I think it can be done. Having people randomly work on > > sections will not produce a coherant manual - central management > > and review is the key. > > Getting any material at all would be pretty key from where I'm standing :) > > The more complex the process, the less likely you are to see anyone going > through with it. 'Having people randomly work on sections' is _exactly_ > what the php.net manual guys do; OSS documentation, like OSS > anything else, > is better demonstrated by watching a nest-ful of ants retrieve a > teaspoonful > of sugar than by anything else I can think of. There's already control > there, in the form of other users, in the form of user notes, and in the > form of peer review (quite a few people have CVS karma for the manual, but > most of them are translators rather than initiators). It's much easier to > get information corrected than it is to get information there in the first > place; witness this list, and the amount of flak the PHP-GTK > manual's taken > over the years for incompleteness, versus the amount of people who have > contributed original material to it. It's always easier to criticise > existing work than it is to produce any. > > At php.net nowadays, the docs team request that new functionality (and new > extensions) are initially documented by the person that wrote that > functionality or extension. This isn't an option we have here; Andrei's > contributed a couple of classes to the manual (and it took him a lot less > time than it would've taken me), but we can hardly ask him to > document 100+ > classes in his spare time. Even if he had any. He automated what he could > and left the rest for people to fill in. In other words, at present - > still - if there are no signals and no properties outlined in a PHP-GTK > class, it's safe to say that that class has never been touched by anyone > writing documentation. > > I should maybe make the secondary point that the GTK+ 1.2.* project itself > had the same documentation problems we face here. That manual was never > completed either. The documentation for GTK 2 is similarly generated but > was better thought through, with the developers getting involved to > introduce new concepts. > > I'm blathering. Sorry :) but all this stuff does need thinking about > before anyone goes to the trouble of setting up an environment that won't > get used, or a second manual, or anything along similar lines. > > - Steph > > -- > PHP-GTK General Mailing List (http://gtk.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php >