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:

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.