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