Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:112031
To: Roman Pronskiy <roman.pronskiy@jetbrains.com>, internals@lists.php.net
References: <CADZ9LSXePBHB6A5xEFGvW9MZ7pOpM0Hht10cjSkBXQnQGSP8dQ@mail.gmail.com>
Message-ID: <cd664401-136f-bd6e-bae9-a70fd65c1eec@allenjb.me.uk>
Date: Mon, 12 Oct 2020 11:47:24 +0100
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:68.0) Gecko/20100101
 Thunderbird/68.12.1
MIME-Version: 1.0
In-Reply-To: <CADZ9LSXePBHB6A5xEFGvW9MZ7pOpM0Hht10cjSkBXQnQGSP8dQ@mail.gmail.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-GB
Subject: Re: [PHP-DEV] PHP 8 release announcement page on php.net
From: php.lists@allenjb.me.uk (AllenJB)


On 12/10/2020 08:56, Roman Pronskiy wrote:
> Hello Internals,
>
> The PHP 8 release is going to be huge, and in some sense, you could
> say it's a whole new language. There is a feeling that more can be
> done to promote it more extensively.
>
> Usually for releases, there’s a short text announcement on php.net.
> This may be okay for minor releases and for people who are deeply
> involved in PHP as they already know about the new features. But for
> the majority of PHP developers and potential PHP developers, it is not
> enough.
>
> So, the idea is to create a separate release announcement landing page
> to achieve the following goals:
>
> – Promote the release of PHP 8 to the PHP developers
> – Promote PHP as a modern language, as well as the PHP 8 release, to
> the general tech audience
>
> Alexander Makarov, myself, and Svetlana Belozerova, a designer from
> JetBrains, have created the following concept:
> https://i.imgur.com/6fKmTyM.jpg
>
> We’d like to hear from you about how you like the idea. If you support
> it, we’ll finish the design and work on a PR against
> github.com/php/web-php with the implementation.
>
> Looking forward to hearing what you think.
>
> Roman Pronskiy,
> PMM at JetBrains


As a developer I don't care for marketing fluff like this. What does 
this provide that the migration appendices and other documentation does 
not? I feel that this kind of page also has a very limited useful lifespan.

As others have commented, I'm not sure what about PHP 8 makes it any 
more of a "whole new language" than many previous releases.


I would much rather see the effort be focused on ensuring the migration 
guides be as complete and concise as possible whilst also ensuring other 
sections of the manual are updated too (information is sometimes only 
found in one or the other - ie. the migration guide is updated but the 
specific manual section is not).

I would say that what might actually help drive upgrades / adoption is 
promotion of tooling that helps detect and automatically update code 
where possible (php-compatibility for CodeSniffer, Rector, etc).

Obviously this starts to infringe on core's ongoing insistence on not 
referencing third party tools, but I feel this could possibly be solved 
with something like Python's Wiki that provides a "less official" area 
for community contributed content and "related content". (It need not 
necessarily be a wiki - it could be, for example, something GitHub powered)

Such an area might also provide an easier to contribute to and more 
easily organised and updated representation for the conferences (which, 
despite being labelled "Upcoming" on the front page makes no real 
distinction and still lists events from 2015 - it might also be useful 
to be able to categorize / filter conferences by geographic, language or 
online/offline) and talks sections of the site.

(I have talked about this before: 
https://externals.io/message/107096#107101 - see also my notes on 
Python's tutorial here and compare that to PHP.net's current official 
tutorial, which still references XForms and has a rather lacking "what's 
next" section)


I also think new releases could be a good point for reviewing existing 
documentation - in some cases I feel that some sections have grown 
unwieldy and hard to use (quickly find what you want) in their current 
form.

An example of this would be 
https://www.php.net/manual/en/language.types.array.php which is quite a 
long read and has no table of contents despite having many sub-sections. 
(A TOC would also help by exposing the section-specific link anchors 
that already exist in the manual but are not obvious unless you use a 
browser plugin that exposes them).

(It also appears to be missing information on array destructuring and 
unpacking features from 7.3 and 7.4 - an example of the specific manual 
sections not being updated that I mentioned earlier)


AllenJB