Re: [PHP4BETA] Re: [PHP-DEV] Re: [PHP4BETA] PHP 4.0.0 Release packaged

Hello Egon,

On 21-May-00 05:38:24, you wrote:

>> - Final releases are done and many new features are not documented.  What
>> is the point of announcing cool features like Shockwave Flash support but
>> users can not find any documentation to use it? This makes the developers
>> look like hackers or just amateurs.

>Which new user needs Shockwave Flash support? The same goes with COM
>support. It was never documented in the manual. COM was present since the
>beginng of PHP 3. Users who needs COM support reads the source code.

That was an unfortunate comparision.  I know what is COM but most people
don't.  As for Shockwave Flash, even designers know what it is.

Dynamic generation for Shockwave Flash output, like there is for GIF and
PDF, will certainly be a killing feature that many PHP enthusiasts will
use in PHP vs.  the world arguments.  That is precisely the problem.
Picture this situation some time soon in a IT department next to you:

Joe Webby, a paid Web developer rushes into his boss office:

- Hey boss, look, PHP 4 final is out and guess what: it is capable of
  generating Shockwave Flash output dynamically!

- Really?  I don't believe that.  It's too good to be true for some free
  Web programming language. Show it to me, I want to see some examples.

- Hold on, I am going to find a sample page to show you.

Joe Webby gets back to his desk trying to find some cool examples.  An half
an hour after he returns to the boss office.

- So, can I see some Flash pages dynamically generated by PHP?

- Humm...  I haven't found anything yet, but I posted a message to the
  mailing list and I am awaiting for an answer.  PHP 4 was just released,
  people is still discovering what's new.

- Ok, but what about some documentation to show how it works?

- Documentation?  Humm...  I haven't found it in the PHP 4 manual, but you
  can always browse the Flash extension C code to figure it out.

- What??!?!  Are you crazy?  Do you think we are going to waste our
  precious time digging someone else's C code to figure how some
  undocumented free software is supposed to be used?  You free software
  maniacs are out of your mind if you think we will do that.

  That's something for college students do because they have plenty of time
  waste while their parents are paying for their studies.  But we don't
  have time for that.  We have work here to do, and soon.

  So get back coding in ASP and don't you ever get back here with any more
  undocumented free software crap!  There is certainly some ASP component
  that do that already.  It costs money but it is certainly documented and
  have personalized support.

It may be amusing but this is realistically sad.  It may have not happened
to you, but it is happening all the time with many PHP enthusiasts.  People
burn themselves and the chances of seeing PHP adopted because releases lack
of professionalism.



>> Developers should be obligated to enter documentation for the functions
>> that add or else they might never be documented at all.  You may claim that
>> developers do not have the time both add code and document their new
>> functions, but I have seen developers that keep adding multiple features
>> and not documenting any.  If you do not have time to document one feature
>> that you add, you certainly will not have time to add other features.

>Together with the above expierenced users use the source code. In
>the case of Shockwave Flash you can use the function prototype together

You are missing the big picture.  Many people that work with PHP don't even
know C at all.


>with the Flash API and start coding. And oh well, the documentation people
>have to do some other work thei are paid for. 

That's no excuse for contributing half done work.  Undocumented features
are as good as non-existing because users work bother to use them and will
only clutter mailing lists asking for something that should be in the
manuals but it isn't.

As I said, I see people contributing with lots of features and don't
document anything they do.  They'd better add half of the features but
document them properly.


>> I know that documenting software is a real drag, but the lack of proper
>> documentation is a big disadvantage of many free software projects that
>> plays against its credibility.  I know that PHP is not the worse documented
>> free software project, but the reality is that many developers rather have
>> to pay for less capable software that is properly documented than using
>> free software that you have to guess how to use it by browsing the source
>> code.

>You should have a look at Hartmut Holzgraefe's nifty PHP Function Table /
>Implementation & Documentation at
>http://www.zugeschaut-und-mitgebaut.de/php/. It is currently on Puretec, a

I have seen that before but you have documenting is not just listing
function names and arguments. There needs to be some examples or tutorial
of how things are supposed to work.  Users are not wizards that guess
everything just by looking at prototypes.


Regards,
Manuel Lemos

Web Programming Components using PHP Classes.
Look at: http://phpclasses.UpperDesign.com/[email protected]
--
E-mail: [email protected]
URL: http://www.mlemos.e-na.net/
PGP key: http://www.mlemos.e-na.net/ManuelLemos.pgp
--