Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125300
Date: Tue, 27 Aug 2024 01:18:34 +0100 (BST)
To: Bob Weinand <bobwei9@hotmail.com>
cc: Jim Winstead <jimw@trainedmonkey.com>, internals@lists.php.net
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party
 Packages in PHP Documentation and Web Projects
In-Reply-To: <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Message-ID: <663bea3c-a8e7-4881-2bcb-971a96dea9cb@php.net>
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com> <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
From: derick@php.net (Derick Rethans)

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