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