Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125337
Feedback-ID: i8414410d:Fastmail
Precedence: bulk
MIME-Version: 1.0
Date: Wed, 28 Aug 2024 08:34:57 -0500
To: "php internals" <internals@lists.php.net>
Message-ID: <819bcfbb-b747-4ed1-a878-bf5a8e00935e@app.fastmail.com>
In-Reply-To: <6B084580-CEFA-45A3-8221-944B9502B745@getmailspring.com>
References: <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
 <6B084580-CEFA-45A3-8221-944B9502B745@getmailspring.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party Packages in
 PHP Documentation and Web Projects
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
From: larry@garfieldtech.com ("Larry Garfield")

On Wed, Aug 28, 2024, at 2:51 AM, John Coggeshall wrote:
>> And that is how you will find that the "new" languages will "win". If we
>> don't promote how modern PHP Development works, then there will be more
>> "PHP, a fractal of bad design" articles to come for decades.
>> 
>> We *must* do better than this. It probably doesn't all need to be in the
>> documentation (doc-en), but it absolutely belongs on our website.
>> 
>
> Hear Hear Derick!! 
>
> I am not advocating that php.net put its finger on the scale in favor 
> of Laravel over others with this comment, but why php.net does not have 
> a documentation analog similar to how Laravel's documentation is set up 
> is beyond me. Useful installation instructions, sections on "How do I 
> do database stuff", "Security", "Filtering Data", "Installing third 
> party packages" etc... there are too many people who have embedded in 
> their brains that PHP is a badly designed language because we don't 
> teach or even advertise to people how to write good PHP code... as 
> others have mentioned as an example, the lack of even a mention of 
> composer on php.net is mind-blowing.
>
> As Derick said, back 20+ years ago PHP had amazing documentation for 
> the times -- miles ahead IMO than most open source projects. But the 
> world has moved on, developers want and need higher level documentation 
> that is more opinionated on not just the dry APIs available you might 
> use to connect to a database (for example), but how to properly connect 
> to a database. Back 20 years ago we had companies like Zend around who 
> devoted considerable resources to filling that gap for the community 
> (along with O'Reilly, etc.) but those entities are gone now and it is 
> up to the project to pick up the slack.
>
> I also think it's a mistake to get too caught up with the concept of 
> "endorsements" and people worrying that "oh gosh if php.net talks about 
> Laravel and Zend Framework then that means something bad for XYZ 
> framework" (pick your favoriate techs here). It's easily solved by 
> having a section on "Popular PHP Frameworks" that explains the concept 
> that PHP as a language doesn't embrace any particular framework, the 
> importance that you do generally want to embrace a framework to do 
> anything serious, and provide a list of popular ones that people 
> commonly turn to when building their apps. As for using a framework or 
> any other PHP-related tech in the project's codebases... I think we're 
> grossly overestimating how much weight that decision would carry with 
> the PHP community at large. Short of the PHP Project stating "X is the 
> official framework of PHP" (and especially if we say "We don't have an 
> official framework but here are good options that are very popular" 
> instead), the concern over the appearance of endorsements at this point 
> is really an invented issue rooted at least in part by historic 
> concerns that simply don't exist anymore.
>
> Coogle

What a couple of people have touched on is that that all we have right now is a Reference, which is only one kind of documentation.  The common zeitgeist these days says there's 4: https://diataxis.fr/

* Tutorials
* How-to guides
* Explanation
* Reference

We have a reference with gaps, and that's about it.  In practice, it will be functionally impossible to write a meaningful tutorial or how-to guide that never mentions anything but php-src-provided code.  Or at least the result would be sub-standard and doing the reader a disservice.

I don't think I'd support a list of "popular" frameworks, but mentioning Composer, Xdebug, and PHPUnit seems a requirement for a useful modern tutorial.

Admittedly, the docs team is very under-resourced right now and even the reference section has not-small holes, making maintaining even more types of documentation a potential challenge.  That's something the Foundation could possibly help with.  But that's not the topic at hand: The topic at hand is just "look, we should be able to mention Composer, Xdebug, and PHPUnit, OK?"  On which I very much am in agreement.

--Larry Garfield