I spent a lot of time recently interacting with some online documentation for a PHP framework that I don't use very often really. But I'm using it more right now because of a contract that I'm working on. And it kind of dawned on me how important it is to understand why various parts of a framework actually exist. And I don't mean that we all need to understand why they exist before we can use the framework. I mean, from the documentation's point of view, that it understands why or the the person who's writing it understands why that part has been built.

Because it's clear from the documentation that I've been reading, that either people either don't know why or they assume that everybody else does know why. But I think documentation is so much clearer and so much easier for people to sort of grasp. Like, especially if there's choice in in what you're writing. Like, if you're writing about a subject matter, let's say it's caching, and you've got multiple ways of doing caching. You know, you might have something that just stores, objects in memory.

Sorry for the non technical people, but you might have a way that stores them to disk or to a database. And though just those three options, that that presents so much like choice to somebody who maybe is new to this concept. What they lack is an understanding of when they should use one over another. And that's what the documentation can I'm not saying it necessarily should, in every case, help them to understand. And this is a contrived example, like most of us probably know what caching is and how, you know, the different options that are available.

But hopefully, you get the point that if the documentation is clear on the why, they can provide that context to people that are reading it. And I think that would be so much more useful. I would love to give a solid example of a situation where this has affected me with this particular documentation. But I don't really wanna call it out too much because I think overall, it's a really good piece of kit. It's just the documentation is really seriously lacking.

I wish I had time to help them sorted out because I think it only takes somebody with a little bit of thought to go in and write some, you know, an extra paragraph about this and that. But it's a it is a lot of work to kind of understand all of these topics well enough and deeply enough, and then be able to write clearly to help people. And that's the point of the documentation, is to help people. Like, especially when it comes to code, you can discover how the thing works by looking at the code. I mean, it's the same with the physical thing.

You can do you can figure out how to work a washing machine or a vacuum cleaner or, you know, an some appliance without the manual. Right? You can press all the buttons, and you can risk breaking the thing. But with the instructions, it will go so much easier. So they're there to help.

So why not make it help? Start with why. Bye.