December 10th, 2020
As you may or may not know, in September 2020, the PHP Documentation Group has retired the manual for end-of-life PHP versions from the php.net site.
Ideally, I'd love to see everyone running the latest version of PHP! But to achieve this, someone has to read the old docs to ensure the application's compatibility with the new PHP version.
I have just migrated my 20th application this year, where I fixed 4 million lines of PHP 5 code to make them compatible with the latest version. I refer to old documentation almost daily in order to understand the PHP 5 vs current behavior. Other people have voiced a similar opinion. Imagine spending hours searching for solutions only to click on a broken link, then having to dig through tarballs.
Here are some reasons provided by the maintainers of the current documentation:
Because everything is on one page, maintaining accurate docs for all versions is rather impractical.
I concur. Currently, documentation pages may have:
We could spend our time on more productive things.
The current documentation team is rather tiny. They can barely keep up with the new releases. Asking them to maintain legacy versions and figuring out how to explain all of that clearly on one page is exacting.
Removing docs alleviates the burden on translations.
At the time of writing, the documentation is available in 10 different languages, so take the points from the previous arguments and increase the effort tenfold.
On the mailing list, we discussed various solutions. I set out with these goals in mind:
Additionally, during the discussion, it became apparent that the current team does not wish to be bothered with bug reports about inaccuracies in the legacy docs. What we needed was a "legacy docs team" which would take away that burden completely off their shoulders.
After toying with various ideas, the following proposal seemed to yield consensus:
So if someone wants to take ownership of that project they are free to do it and we can possibly sort out some way to link to it from the official docs with a disclaimer that doc bugs about the legacy docs should be redirect to that specific team.
I went and did just that.
I put on my diplomacy hat and convinced Zend, one of my current clients, to support this initiative. To my delight, they agreed to dedicate both hosting resources and development time for maintaining the legacy docs. I went ahead and published them, which wasn't as trivial as some might think. I had to:
Now I just need to get the search working and we're in good shape. I expect to dedicate time each week to the maintenance of the legacy docs and hopefully build a community around them.