Re: [PHP-GTK] Status of PHP-GTK

Benjamin Smith wrote:
> I offer some counter points, here... 
> 
> On Wednesday 15 April 2009 06:53:48 Bob Majdak Jr wrote:
>> Coding is really limping along just fine. Tonnes of people hate the
>> docs, less than tonnes offer to help,  none of them actually do. 
> 
> Sometime ago, I was offered the opportunity to update the docs, and was 
> picturing that it would be something like a fancy wiki or somesuch. Instead, I 
> was introduced to text files with a very complicated tagging system and a steep 
> learning curve. I don't remember what it was, it's been a few years, and I'm 
> sure there are good reasons for choosing it. 

That's DocBook, and the original reason for using it - as now apparently - was to stay in line with the PHP Manual proper. Livedocs was an attempt at addressing the complexity; phd is an attempt to reduce the need for external tools and hence the learning curve, but you still need to be able to use DocBook XML in order to write manual content for php.net.
 
> After struggling for some hours over a few days on it (and even starting a 
> docs editor in PHP-GTK to manage some of the complexity) I threw in the towel 
> and resigned myself to leaving (hopefully helpful) comments. 
> 
> Can this be made simpler? Do you know of some kind of doc-editor manager 
> doohickey to take track all the tagging?

Nope. (Doesn't mean there aren't any, just means I don't know of any.)

>> Granted
>> extra coders would help but patch writers are easier to come across than
>> people actually willing to do the docs. And the coders can usually
>> figure out what to do by knowing  GTK in C or by looking at the C GTK
>> manual.
> 
> Get_class_methods() and get_object_vars(), and Google are my substitutes. I 
> make it a point to leave notes when I can. 

Yes, and yours were reliably good notes too. 

>> The PHP doc system i am sure is not going anywhere, and personally I
>> like comments off, it is a manual not a wbe forum.  That is one of the
>> things I hate the most about the actual PHP docs, especally when a new
>> guy posts a code sample that is horrid and the next 20 posts are people
>> saying "oh hay i made this better". I am not being bitter. Honest.
> 
> It's common for me to be baffled by minimalist docs, only to find a comment that 
> makes it all clear... I'm perfectly willing to ignore the crappy, 3-page-long 
> code samples in order to have the nuggets that make my day! And sometimes, 
> even the 3-page-long crappy code gives enough detail about how to use XYX 
> function that it's useful. 
> 
> ...perhaps a moderation system for comments? 

That's the thing I was writing when I ran out of time (which is why there aren't notes now). At that point, the PHP Manual notes system had been taken down by spammers and we also didn't have access to master.php.net for PHP-GTK Manual notes administration. So I started out writing a lightweight system that could be hosted on 'our' server, but then work went a bit mad and that was the end of that project. The entire PHP-GTK website was already in a bad way at that point - it just hadn't had any love since inception - so although getting notes live shouldn't be a major task at this point, nobody's going to be able to look at the site code without feeling swamped by need-to-do's. I suspect this is the point Maddy reached.

Notes administration itself is an ongoing and time-consuming job, and there are never enough volunteers for it regards the PHP Manual. (NB Notes admin is _much_ easier than writing docs.)

- Steph