The documentation reads like a tutorial, which is fine the first time you read it, and really annoying the next 99 times when you're just trying to find something. My biggest gripe though is that the majority of classes / methods aren't locally documented with comments, or only minimally. If I don't understand how a certain parameter behaves (or even what a function does), I have to go online and search for examples, or look through the docs hoping that it's explained. And don't get me started on Facades, which are a code discovery dead end...

All that being said, my overall experience of working with PHP / Laravel is quite pleasant, probably more so than other technologies I've worked with in recent years. Everything has its issues I suppose.

Yep, the tutorials/guides are really good, but as you say, the details aren't really covered. There are so many examples like "relationsToArray(): Get the model's relationships in array form."[1] Just an expanded version of the method name with no context or detail.

[1]: https://laravel.com/api/10.x/Illuminate/Database/Eloquent/Mo...

The good ol' "you thought docs, but actually generated no information gain and no docs, ha tricked you! but look at how fancy our docs website looks" kind of documentation style.

> The documentation reads like a tutorial, which is fine the first time you read it, and really annoying the next 99 times when you're just trying to find something.

Ah yes, the Ansible approach. I've used it for a decade, and I routinely get lost in its utterly terrible by-example documentation.

They are the golden standard on how not to write documentation.

God, I hate the Ansible docs so much, they are the reason I burned 30% of my Kagi search quota this month.

I think more documentation teams need to know of the concept of Diataxis [1] so they can invest in the 4 different kinds of documentation developers turn to for help when picking up a new technology:

- tutorials;

- how-to guides;

- technical reference and;

- explanation.

1: https://diataxis.fr

This looks very nice and is something I have been searching for but didn't know existed. Thank you!

See also the C4 model "for visualising software architecture". https://c4model.com/

Thanks for this. This is something I kind of knew but would have been hard pressed to articulate, especially on the spot. Seeing it laid out like this is very useful.

For stuff like Ansible (and other lacking software) docs i find that ChatGPT can provide the missing pieces.

What is wrong with the Ansible documentation?! Almost all Ansible module documentation pages follow the same structure: a one-sentence synopsis, a list of OS packages needed to be present on the machine where Ansible runs and on the target machine, a table of parameters including aliases, default values and other hints, a list of attributes exported, some notes, and real-world examples.

It doesn't get more clear than that.

Outside of modules documentation, the rest of Ansible docs are examples. For instance, there is no page where all ways of accessing inventory variables are listed. Or supported jinja filters. They are all scattered in a myriad of examples, which you have to read, carefully, to find what you need.

https://docs.ansible.com/ansible/latest/playbook_guide/playb...

On this page there is no quick index of all the functions available, their argument and a short summary of how they work. You need to synthesize this information yourself by reading through ALL the examples, and hoping your niche use case is listed.

There are more than one type of documentation, with different use cases. There's the tutorial/list of examples, which Ansible excels at, and is ideal for a first timer reading the docs from cover to cover. Then there's the API reference with quick index, for intermediate to advanced users, where they know roughly what they need, they just need to find it. In this, Ansible's docs fail dramatically.

I am certainly not one to defend the new ansible docs, but part of the woes that you're describing are due to the fact they just doubled down on `ansible-galaxy install` based setups, meaning there isn't "an answer" to what filters are available in ansible

The authoritative answer to what filters are currently available in your distribution is by running `ansible-doc -t filter --list` which does include a summary line, although for some of them it's "geez, thanks" just like any open source collection of disparate modules glued together

I used to actually build the ansible docs locally with singlehtml because I despised that chopped-up view, but now that they're all "galaxy all the things" it's practically useless again (although I will also say that building it locally and eliding all their tracking bullshit makes the pages load like a bazillion times faster, so ... still valuable in that way)

What "computer science terms" did you encounter, that you did not understand? I also do not have a CS degree, but every term that I've encountered in the Laravel docs I found easy to search for. Just don't rely on Wikipedia for explanations, for CS (and mathematics) subjects Wikipedia seems to be useful only to those already versed in the field.

I struggled with sorting out Contracts vs Facades vs Traits. I graduated from university 20 years ago with a software engineering degree, where it was drummed into me that simpler often is better, and much more robust. Reading the Laravel docs however, leaves more questions than I started off with.

eg. https://laravel.com/docs/5.8/contracts – talks a lot about how Contracts are powerful additions (like all the other features of Laravel, the docs are good at telling you they're powerful) and the examples show just some barebones code that doesn't really do much without a lot more work. The examples in the documentation seem to be more on the side of being some code snippets that don't convey much context.

Additionally, there's lots of "congratulatory" text in the documentation ("Laravel has a powerful feature called <x>", "in Laravel adding <feature y> is actually really simple", "some developers enjoy using <feature z>". You simply don't see this in PHP.net's docs, it just tells you what the function / feature is, gives you examples that work straight out of the box, lets you know of any pitfalls or differences in PHP versions to watch out for, and there's a whole list of comments contributed by other PHP devs spanning years, that are up/downvoted.

Another example of powerful documentation was that I learnt what MPTT is, and how to implement it effectively, purely from CakePHP docs back in the day (I'm talking v2 here). I can't see how anything as remotely useful would be able to be taught from Laravel docs alone; for someone who doesn't have a computer science degree, there would be a LOT of tabs open, full of rabbit holes that need to be explored. This is not effective documentation in my eyes.

The difference between these sets of documentation is like night and day to me. The Laravel docs needs to stop patting itself on the back, and be more like other software projects' documentation.

Don't get me wrong, I love working with Laravel, it is powerful. My issue is with the documentation, which leaves a lot to be desired.

The project is in a constant state of flux. So for example the Contracts you cited are in version 5.8 but they are no longer in the current versions.

Right, but this is a discussion about their documentation, not whether Feature X in a version of Laravel is still around in the latest version. I'm not attacking the framework, as I said I love using Laravel. I just have criticism about their documentation.

The 5.8 docs are like from like 7 or 8 years ago. I’d say the 10.x docs have improved a lot, but I do share some of your opinions on the docs in general. Anyone can contribute to them, though. https://laravel.com/docs/10.x/contracts

Laravel focus a lot on branding & communication to create a hype by overselling their functionality, you are a "Web artisan" when using it, the ORM is not like other ORMs, it is an Eloquent ORM etc.

A facade cuts out the boilerplate to achieve the same ends as a contract, which is to provide a dependency of some kind.

I agree with the documentation sentiment. The documentation is enough to get one started, but not nearly enough to get the job done well. The community is overran with beginners, and you are left to your own devices once you really want to get your hands dirty.

The documentation for Laravel is still unreadable.

Guess that is why selling Laravel tutorials seems to be a fruitful business.

But why? I‘m working with it daily and what I learned is to read the docs properly. Usually it‘s me not reading correctly. There is some advanced stuff that‘s not covered in the docs, but not necessary to build an app.

That's exactly the point: a documentation should be comprehensive, i.e. it for each class and each method it should describe exactly what the method does, including all parameters etc. The Laravel "documentation" is a tutorial, i.e. it describes what you should do for the most common use cases in a style designed to be read from beginning to end. Which has its uses too, but as documentation, it's pretty lacking...

Laravel tutorials are a fruitful business because PHP still quite rightfully carries its legacy of being the noob language.

I’m sure that plenty of us used PHP in the day, have been doing something else for a while, and see these HN posts from the people that stuck by PHP singing its praises. Let’s not forget that there’s probably been a steady stream of newbies coming through the system the entire time - which makes the language, and by extension Laravel, a prime target for bottom feeding ‘one step ahead of the audience’ “educational” content producing scum.

The documentation for Laravel is readable, in the sense that if you read it from beginning to end, like a book or tutorial, you will get a pretty good understanding of what Laravel does. But [supreme being of your choice] help you if you just want to find out what the possible values for a specific parameter of a specific method can be...

Nah. It's pretty bad. They only document like 5% of the features. What they do document is good but other than that you have to read the source on GitHub or Google for code snippets and I say this as an expert that studied the docs for help in documenting my own orm. They just straight up don't document most of Eloquent's features and class methods in the docs at all and it's super frustrating to me.

What are the “computer science terms”? I went looking in the docs briefly but didn’t find anything like that. Maybe the v10 docs do better? https://laravel.com/docs/10.x/blade

there are many documentations tells you the detail in their code.... even with the most basic usage

Really? I don't have a comp sci degree either, and yet I find the Laravel docs incredibly easy to grok. Do you have any specific examples of things you've struggled to understand?

Agree. Last time I tried Laravel the documentation was lacking a bit. E.g. there are lot of "automagic" things that aren't explained. And then you are left wondering with things like "Must the names of those 2 things really match for it to work?".