Like every other god damn question I ever ask on this site, this was apparently "off-topic" even on Stack Overflow. That’s why I ask it here, the only other fitting category I could find.
What strikes me is how ancient typos are still there, ones I remember from the early 2000s. The user-submitted comments can say "17 years ago" and things like that, which makes me feel as if I’ve discovered some ancient dwarf book in Moria or something, almost falling apart from age. But it’s the live, current manual for PHP.
This makes me feel uneasy to say the least. I’m not going to pretend as if the manuals for other free software is better. In fact, they are usually much worse, but the fact remains that I use PHP so heavily and have so much of my life invested in it (I’ve now used PHP far longer than I had existed at the time when I first started using it), and so frequently look in its manual, that it means a lot to me.
And it should mean a lot to others as well, considering that it’s one of the most used programming languages in the world.
The code examples are frequently ancient, irrelevant and unclear. I’ve rarely had any use of those, instead being forced to guess my way to how you’re supposed to use the functions, or had to ask on Stack Exchange or read its old questions. Those user-submitted comments are also rarely of any value, frequently dangerously misleading and horribly insecure.
It seems as if somebody should have long ago been paid a full-time salary to painstakingly go through the entire PHP manual and fix all typos, bad descriptions, poor examples, and clean up the mess of user-submitted comments. I also wonder if they have turned off new comments from users or something, because so few of them seem to be made in the last few years. I assume that they have a manual review system in place, and maybe a huge backlog with nobody looking at it?
Why, for such a massively popular language/project, has not one company stepped up to pay for such a single person to do this work? It’s downright embarrassing when the manual is this state.
I can predict the answer:
Why don’t you do it? Patches/donations welcome.
I don’t do it because I’m overwhelmed by just trying to use PHP. I have no peace of mind, a stable life situation, nor even the skills, to fix the PHP manual. But I know that there are many individuals out there who do have peace of mind, a stable life situation (an income), and far better skills than I and who could in theory do it. But they don’t. For some reason.
I’m not calling them evil/lazy. I’m just wondering how this situation can be. It’s depressing. Baffling. Makes me feel as if I’m using some sort of legacy application.
I’ve countless times gone hunting for "PHP alternatives", many times asking people about it, etc., but not once have they been able to present me with a valid alternative, so I’ve stuck to PHP. Also, it would have to be pretty darn fantastic for me to just abandon my entire system and start trying to remake it in some other language which doesn’t even seem to exist. The alternatives mentioned always have some major problem which is far worse than PHP’s issues, such as Python with its major incompatibilities between versions which makes PHP appear stable as a rock.
But this question isn’t about possible PHP alternatives. It’s about why the PHP manual is in such a perpetually miserable and "rotting" state.
I’ve also discovered parts of the manual, probably for classes/functions added in recent years, which aren’t "commented" at all, but seemingly simply generated from source code. Yet they still develop the language itself, and it’s improved all the time. But the manual doesn’t really reflect any of this; it makes the PHP project seem almost abandoned.
I don’t understand it. If I ever make it and start actually making money, I’m going to seriously consider hiring somebody to brush up the PHP manual. It’s the least I could do to give back, and it frankly makes me angry that nobody else has ever thought like this. Or maybe there are no previously-poor people out there who "made it" rich by using PHP? (Seems unlikely.)