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