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

On Friday 17 April 2009 08:28:09 Justin Martin wrote:
> I am quite well versed in PHP-GTK,
> but I know next to nothing about the documentation system.

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. 

It's a horrible choice: Red Pill or Blue Pill? 

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. 

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! 

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) 

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.
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, 
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'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. 

-Ben 

-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.