Re: Maintaining PHP 5 documentation

Andreas,

Hm, I don't think that it would allow us to do things like clean the legacy
docs of unnecessary references to newer behavior or fix pre-existing issues
in the legacy docs. Since major versions coexist for a time, I assume
there's no clean cutoff point in the revisions. Here's my vision of the
docs. Let me know what you like and what you don't, and propose
alternatives.

- Current manual located at /manual/en. Only currently supported versions
of PHP are referenced here, with links to legacy docs.
- Legacy docs located at /manual/php5/en. Only PHP 5.x versions are
references, with links to other legacy versions and/or the current version.
<-- I can find resources/financing to manage the legacy docs, including
hosting.

I'm trying to find a solution that is both good for the devs but also
requires no ongoing effort from the docs team.

Anna

On Fri, Dec 4, 2020 at 2:52 PM Andreas Heigl <[email protected]> wrote:

> We could think about building docs for a certain tag/revision or branching
> of a PHP5 (as well as a PHP7?) release branch for the docs as well. And
> then build the docs from those branches.
>
> Cheers
>
> Andreas
>
> 04.12.2020 20:46:55 Anna Filina <[email protected]>:
>
> > Thanks for such a detailed answer!
> >
> > Would it make sense for someone to maintain a completely separate manual
> specifically for those retired docs?
> >
> > Advantages:
> > - The rest of the team could maintain only docs for the current versions.
> > - The legacy docs would still be online, searchable and linkable.
> >
> > I can find the resources necessary to make this work.
> >
> > Anna
> >
> > On Fri, Dec 4, 2020 at 2:24 PM G. P. B. <[email protected]>
> wrote:
> >> On Fri, 4 Dec 2020 at 19:01, Anna Filina <[email protected]> wrote:
> >>> Hi team,
> >>>
> >>> 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[http://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?
> >>
> >> We don't have multiple copies of the docs so everything lives on one
> page.
> >> There is an archive of the PHP Documentation before we started removing
> mentions of it.
> >> Akin to how the PHP 4 docs are handled.
> >>
> >>
> >>> - How much effort does it require to maintain the legacy docs?
> >>
> >> Because everything is on one page, maintaining accurate docs for the
> range PHP 5 - 8
> >> is rather impractical, many things changed, functions got removed,
> functions had drastic
> >> behavioural changes, etc.
> >>
> >>> - Are there any associated costs?
> >>
> >> The human cost of needing to maintain such a large range of versions
> and to maintain
> >> and clarify docs which are only relevant to PHP 5 when we could spend
> our time on
> >> more productive things.
> >> Secondly removing docs alleviates the burden on translations.
> >>
> >>> Thanks,
> >>> Anna Filina
> >>> https://twitter.com/afilina (DMs are open)
> >>
> >> Hope this clarifies some of it.
> >>
> >> Best regards,
> >>
> >> George P. Banyard
>