Re: Maintaining PHP 5 documentation

On 04.12.2020 at 20:17, Gabriel Caruso wrote:

> On Fri, Dec 4, 2020, 16:14 Gabriel Caruso <[email protected]> wrote:
>
>> On Fri, Dec 4, 2020, 16:01 Anna Filina <[email protected]> wrote:
>>
>>> I landed on this plain 404 page yesterday:
>>> https://www.php.net/manual/en/ini.sect.safe-mode.php#ini.safe-mode
>>>
>>> I was told that the PHP 5 docs are in the process of being removed from
>>> php.net. This is not ideal for me as I maintain and migrate legacy
>>> applications for a living.
>>>
>>> I would like to understand the reasoning behind this decision and perhaps
>>> offer some help to remedy the situation:
>>> - Are there any inherent problems with keeping the legacy docs online?
>>> - How much effort does it require to maintain the legacy docs?
>>> - Are there any associated costs?
>>
>> I believe this was the PR archiving it:
>> https://github.com/php/web-php/pull/341
>>
>> I'll check in the mailing list of there's a discussion thread meanwhile.
>
> There you go: https://news-web.php.net/php.doc/969387511

That message referred to another thread, which is
<https://marc.info/?l=phpdoc&m=157659936427907&w=2>.

The basic problem with maintaining documentation for PHP 5 is the
overhead for maintainers (who are not as numerous as the stars in the
sky; actually it's more like the number of planets you can see in the
sky with the naked eye), *and* for most readers (there are sometimes
long changelog lists, and some notes sprinkled through the text
regarding behavior as of, or prior to certain PHP versions).  See, for
instance, the documentation of debug_zval_dump()[1] which is completely
outdated; the presented example doesn't even work as of PHP 5.4.0 (as
pointed out in some of the user notes).  There has been discussion about
this function several years ago, but still nobody updated these docs so far.

This is even amplified by the release of PHP 8.0.0, which requires
plenty of documentation (updates), and it is already hard enough to
track function signature changes between PHP 7 and 8, for instance.

On 04.12.2020 at 20:39, Anna Filina wrote:

> Would it make sense for someone to maintain a completely separate
manual> specifically for those retired docs?
That might make sense (but may be a lot of work).  An alternative might
be to just make the archived documentation available online.

[1] <https://www.php.net/debug_zval_dump>

Regards,
Christoph