On Mon, 26 Aug 2024, Bob Weinand wrote: > On 26.8.2024 19:44:18, Jim Winstead wrote: > > > > Another RFC around process: > > https://wiki.php.net/rfc/web-and-doc-use-not-endorsement > > > > Feedback would be appreciated. My intention is to start voting on > > September 9th unless there is still ongoing discussion. > > Thanks for bringing this up - I also suggest that we make this a > binary choice - either we adopt the proposed language or its opposite. > > I.e. a rejection of this should codify that statement in the negative. > > I do in particular reject the notion that we should document > third-party projects (usage for our infra is fine).
I think this is short-sighted. Currently, our main website, php.net, does not have useful installation instructions. We have a "Download" tab, which points to tarballs. Who still installs tarballs like this? Nobody does. It's either distribution packages, or installers such as XAMPP, or MAMP, or whatever. We are doing our (potential) users a disservice by not explaining the reasonable ways of installing PHP. We should replace our "Download" page with something that people would actually benefit from. Just like our home page is just boring release announcements. This should have much more interesting stuff such as how, and when, to use the great new features that we have been adding in the last decade. > The point of the PHP documentation is to describe the PHP runtime and > PECL extensions, which are both officially distributed through > php.net. I also think we are not doing PHP a favour by refusing to mention the main way how developers now install libraries: Composer. It doesn't have to be a comprehensive guide, but it is ludicrous to not even have a page in our documentation that describes how modern PHP applications get (and should) get bootstrapped. We will have the same argument eith PIE (working title) soon too. Should we promote a specific framework? No, probably not. Should we endeavour to rewrite all of our internal stuff in Symfony, or Laravel, or Nette, or Zend Framework. Also very much not. But not even have a *link* to Composer and how it used for modern PHP development is just plain stupid, like having a most light hint at how you effectively debug PHP code. Our users *want* to know how to do things properly, and the documentation needs to reflect that. > Anything not related to these does not belong into the manual, much > less into core documentation (like language/oop5 autoload.xml, to take > the example from https://github.com/php/doc-en/pull/3677/files). Where PHP originally had the arguably the best documentation, this has slipped. Our langauge sections in the manual are dry, and only explain what the language syntax are. It doesn't describe how these features are useful, when you might want to use them, what related development patterns and practises are. This *absolutely* belongs in our documentation. > Changing this current unwritten rule is an invitation to implicitly > promote specific projects. The question is really where does it end? > Would we for example also mention PSRs as "widely followed guidelines > for interoperability" or something? It's a strong invitation for some > scope creep. Why not? It's how modern PHP development works. We don't have to go into the intricacies on how PSRs get developed, but not even mentioning best practises doesn't seem particularly useful. > There are, ultimately, enough ways for people to learn about the PHP > ecosystem, the php.net documentation is none of them. If I go to > php.net, it's because I want to learn about the runtime, not its > ecosystem. 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. cheers, Derick
