4 ms·

> Laravel is [...] reasonably well documented Hard disagree. Sorry, I don't have a computer science degree, why does their documentation make that assumption.

> Laravel is [...] reasonably well documented Hard disagree. Sorry, I don't have a computer science degree, why does their documentation make that assumption. I find their docs very hard to grok. PHP.net docs are no-frills no-fuss, straight to the point. Other frameworks are documented very well too, CakePHP comes to mind (at least, when I was using it last in v2 and v3). I can't say I've read the absolute latest version of their v10 docs, but when I was neck deep in 5.8 I found I had to switch to older versions of the documentation to read up on some of the most basic of Laravel features. eg. What's the syntax of using Form in Blade templates? I had to go back to v4.x docs to read up on it, Blade templating hardly got a mention in v5.x documentation, despite it being critical component in a Laravel application. If there was a bug in a project and I had management breathing a fire down at me because it's breaking the site / losing sales / stopping monthly reports from going out, I shouldn't need to decode computer science terms, or look through previous versions of documentation to find the solution. This is why, in my opinion, Laravel documentation sucks hard.

Elte 3y ago
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.
- crabmusket 3y ago
  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/Model.html https://laravel.com/api/10.x/Illuminate/Database/Eloquent/Mo...
  - zelphirkalt 3y ago
    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.
- sph 3y ago
  > 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.
  - ayewo 3y ago
    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 https://diataxis.fr
    - a_subsystem 3y ago
      This looks very nice and is something I have been searching for but didn't know existed. Thank you!
      - tepitoperrito 3y ago
        See also the C4 model "for visualising software architecture". https://c4model.com/ https://c4model.com/
    - maw 3y ago
      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.
  - kristofferg 3y ago
    For stuff like Ansible (and other lacking software) docs i find that ChatGPT can provide the missing pieces.
  - mschuster91 3y ago
dotancohen 3y ago
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.
- acherion 3y ago
  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 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.
  - 3y ago
naiv 3y ago
The documentation for Laravel is still unreadable. Guess that is why selling Laravel tutorials seems to be a fruitful business.
- myspy 3y ago
  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.
  - rob74 3y ago
    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...
- KyeRussell 3y ago
  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.
- rob74 3y ago
  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...
jitl 3y ago
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 https://laravel.com/docs/10.x/blade
whc 3y ago
there are many documentations tells you the detail in their code.... even with the most basic usage
bearmode 3y ago
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?
Double_a_92 3y ago
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?".

Elte 3y ago

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.

crabmusket 3y ago
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/Model.html https://laravel.com/api/10.x/Illuminate/Database/Eloquent/Mo...
- zelphirkalt 3y ago
  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.
sph 3y ago
> 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.
- ayewo 3y ago
  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 https://diataxis.fr
  - a_subsystem 3y ago
    This looks very nice and is something I have been searching for but didn't know existed. Thank you!
    - tepitoperrito 3y ago
      See also the C4 model "for visualising software architecture". https://c4model.com/ https://c4model.com/
  - maw 3y ago
    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.
- kristofferg 3y ago
  For stuff like Ansible (and other lacking software) docs i find that ChatGPT can provide the missing pieces.
- mschuster91 3y ago

dotancohen 3y ago

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.

acherion 3y ago
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 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.
- 3y ago

naiv 3y ago

The documentation for Laravel is still unreadable. Guess that is why selling Laravel tutorials seems to be a fruitful business.

myspy 3y ago
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.
- rob74 3y ago
  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...
KyeRussell 3y ago
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.
rob74 3y ago
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...

jitl 3y ago

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 https://laravel.com/docs/10.x/blade

whc 3y ago

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

bearmode 3y ago

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?

Double_a_92 3y ago

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?".