On Monday, 26 August 2024 at 20:06, Bob Weinand <bobw...@hotmail.com> wrote:
> I do in particular reject the notion that we should document third-party > projects (usage for our infra is fine). > > The point of the PHP documentation is to describe the PHP runtime and PECL > extensions, which are both officially distributed through php.net. > > 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). > > 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. > > As such I strongly condemn the idea of inclusion of this guideline. > > 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. As someone that has maintained the docs for a few years, there are a couple of misconceptions here. We ***already*** promote some projects in favour of others, namely in the installation sections. We promote some cloud vendors, but not all. [1] We promote some installation methods, but not all, and when one project wrote docs to be included it has remained in limbo for 2 years. [2] Moreover, we promote some conferences, but not others (and this is mainly due to if people figure out how to submit a PR on web-php). We even have a calendar of meetups, which is all likely hood is severely out of date: https://www.php.net/cal.php > Moreover, PECL extensions are part of the PHP ecosystem and not the runtime, so why do *some* PECL extension have the right to live on the php.net website, but not others? And frankly, I would prefer that we would get rid of PECL extension from the php.net documentation, as most of them are in a terrrible state with no way for us to easily improve on them, except that it is somehow the responsability of the doc team to do it. As such the statement that the php.net website and it's documentation is not for people to learn about the PHP ecosystem seems blatently false. Because it is, and has been for a very long time. Thus, in my opinion, your current position is non-sensical. Either the php.net website should not endorse *any* external project, which mean no mention of Apache, Cloud vendors, PECL extensions, NGNIX, XAMPP, WampServer, etc. Or we continue to do this, and provide clear guidelines and procedures on how a project can be added onto the php.net documentation. Composer is a de-facto standard of the PHP ecosystem, more than the V8js, Seaslog, or Recode PECL extensions. The fact we don't even _mention_ Composer, or another place where one can learn about the PHP ecosystem on the php.net website is frankly outrageous. The Python.org website mentions Pypi, various IDEs, and even books that people can use to learn Python. Heck, it even has a community Job board. The go.dev mainpage even promotes companies that use Go. Similarly rust-lang.org promotes companies that use Rust in production and IDEs that have first class support for writing Rust. ruby-lang.org has a community tab, but even the documentation tab promotes external tutorials. Similarly elixir-lang.org does the same and promotes companies, and books. I'm pretty sure if I continue looking at the websites for various programming languages I can find more and more examples. And the reson for this, is people new to the language don't know where to go looking and which resources are somewhat reasonable. Having the php.net website point to various curated tutorials, industry standard packages and tools, seems fairly natural. And not doing this clearly makes us an outlier rather than the norm. This is not to say we should mention everything under the sun on the website, but this is where designing a process on how to decide on this comes into place. Best regards, Gina P. Banyard [1] https://www.php.net/manual/en/install.cloud.php [2] https://github.com/php/doc-en/pull/1674
