Poor Documentation = Poor Culture?
“You mean the docs must be changed?! Why? For your ego??” was the response I received on the Larachat Slack forums (of the famous Laravel PHP framework) one day.
The gentleman was a veteran on the forums, and the argument I had wasn’t even a bad one. The exact details escape me, but my point was that I couldn’t figure out how to pass route params in the case of reverse routing. The docs had both the examples, route params as well as reverse routing, separately, but the resulting syntax when these two ideas would be combined wasn’t there.
This gentleman argued that I was dumb and that the whole thing was pretty darned obvious, to which I persisted that it wasn’t and said that the docs should be updated to reflect my use case. Needless to say, the whole chat got involved, and while many people told me I was “technically correct”, nobody supported me or told this ogre to pipe down. It’s hard to believe that this person was from the core Laravel (docs) team, but if they were, boy were the rumors of toxic individuals true!
I persisted for some time, but soon saw that for some reason nobody was going to address the elephant in the room, and quit the forums. Pretty soon, I quit the framework and the whole stupid language as well (though this was brewing in my mind since a long time ago).
But the whole episode tells us a few things:
- Laravel docs are bad. Like, really bad. They are written for people already well-versed in Laravel, and especially if they’re in a hurry. When I complain about docs and people tell me to shut my over-privileged mouth, I show them the Django docs and tell them to go stuff their heads where sun don’t shine. Maybe the whole Python gang has spoiled me indeed!
- Open Source isn’t rosy from any angle. The more you dive in, the more shit-smeared you’ll come out. It’s sad that Open Source participation has become a social pressure of sorts for devs. Sure, the dev world of today is built on the sweat and blood of a few generous developers, but that doesn’t mean we should drop the actually sensible stuff and join the sacrificial row of self-abuse on the Altar of Pull Requests.
- PHP community is bad. Really bad. Really, really bad. Other than making ORM calls, most people don’t understand much in the larger perspective, and there’s less than zero enthusiasm for coaching,teaching, and improving things. No dobut the salaries in the PHP world are less than shit-sprinkled peanuts.
- The Larachat Slack community is bad. Like, really bad. It should be avoided like plague. I don’t understand where the hubris comes from, but I can understand how lost infants would start worshipping a rouge father-figure like Taylor Otwell. Reminds me of the blind followers of certain stupid politicians and tech “magicians”.
Documentation comes in many forms, but not all forms are created equal (this deserves a separate blog post of its own). Documentation succeeds when it’s driven by empathy (not AI, lol) and succeeds in helping someone achieve something. Otherwise, no matter how much effort was put into it, no matter how many pages it has, no matter how incredibly modern/lean the design is, it’s just virtual toilet paper.