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
