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

Hi Benjamin,

> This scenario is exactly what's got this list so active over the past few 
> days. You're not the only one in this exact boat. Picking up YADL (Yet Another 
> Documentation Language) is something that raises the bar to contribution 
> considerably. 

XML is Yet Another Documentation Language?

> Due to the PHP.net frameworks and tools that already exist, there is good 
> reason to stick with their documentation format at the cost of making it 
> considerably more difficult (less likely) for developers (such as Madeleine and 
> myself) who write lots of PHP-GTK code but don't actually develop the code 
> base itself to contribute documentation. I can't comment on the quality of 
> these PHP tools, but I'm sure they are quite useful for administrators. 

These PHP tools (AKA phd) simply build the docs. You can try it out with phpdoc, where it's already used, if you're interested. It renders a whole lot faster than xsltproc, and it also means you don't need any further tools beyond PHP itself to build the manual. I'm not 100% sure what the benefit of live updates is - possibly the idea is that you can build the docs locally then make alterations via the browser, rebuild to test, commit. That would make sense because it removes the XML 'barrier to entry'.

> But I am not likely to dive into source code and learn a new documentation 
> markup language so that I can authoritatively document that you have to 
> reference a child widget in a particular, non-standard way with widget XYZ.
> 
> But that information is still very useful information to somebody using PHP-
> GTK!

So we fix user notes et voila, the info is available.

> Would it be possible to embed an wiki into the documentation so that  
> inaccurate or weak information can be simply deleted? (rather than just 
> commented on, as in comments)

What's the difference, really? Inaccurate or weak info can be deleted anyway, or moved into the manual and given 'official' status. There are a _lot_ of people with php-gtk-doc access, and over 2,000 people with access to notes admin (both for the PHP manual and for the PHP-GTK manual, anyone with a php.net account of any kind can edit user notes.)

> This would provide basically three tiers of documentation on the same page: 
> 
> 1) The "root" documentation, in the tagged documentation format, edited only 
> by language developers.

Why so? I wrote half the first manual without being a language developer. I also wrote a previous unofficial manual from a user perspective, back in the day; the biggest problem with that was that I didn't know why things were as they were, so I couldn't explain behaviours.

> 2) The "wiki" documentation, edited only by proven PHP-GTK developers who 
> aren't necessarily up to #1 above, but have been given access to update the 
> wiki-appended documentation,

We could (once notes are rolling) open up access to notes. There is a precedent for this: there are people with editing rights for the PHP manual notes who do not have a CVS account.

> 3) Comments, contributed by end users.
> 
> This isn't hard to set up since string manipulation is PHP's home turf, and I 
> *am* volunteering to help set this up.

I had it to trial status before now; still in CVS; nobody's touched it in the last 3 years but it doesn't mean the code isn't there. In fact I've been looking at it today... the problems with it were 1) I hadn't made it easy to set up a local version (have done so locally now), and 2) I'd some clever idea about using the php.net NNTP server rather than actual people to control the notes queue. That part really didn't pan out and I'll happily spend the next hour or so killing it. The rest of the system appears to work fine, just we'd need willing moderators to join the ML where notifications are sent. According to the config file, that would be the php-gtk-webmaster list.

Anyone with a php.net address can log into the admin page, but auth is further restricted via whitelisting for some activities. Restricted access does not currently include the ability to edit the existing notes (from the former manual), but does include core items like the ability to turn notes or email notifications on or off.

> I've done something similar in commercial web-based products I've worked on in 
> the past, so that "administrators" (non-programming staff) can update 
> documentation easily for a given page of our product without making them be 
> programmers. It works rather well. Typically, I fashion a wiki-url with a bit 
> of string manipulation from the URL of the page, and make an RPC call to the 
> wiki to get the document(s) in question. 
> 
> The wiki itself (EG: phpwiki) can be hosted at an unpublished url, and can be 
> password protected. 

What's the difference between a password-protected wiki and password-protected notes admin?

I'd be bothered about hosting a wiki on a php.net server again, following the experience we had last time around. So the part about the 'unpublished url' sounds good, but then - Frederic has a rather good community site that already offers this kind of approach. Why not just make more of the community sites from the project homepage, thereby allowing php.net to do what it does best and the community sites to do what they do best?

- Steph

> 
> -Ben 
>