6 ms·
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 somethi
by 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 agoYep, 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 agoThe 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.
- kristofferg 3y agoFor stuff like Ansible (and other lacking software) docs i find that ChatGPT can provide the missing pieces.
- ayewo 3y agoI 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 agoThis looks very nice and is something I have been searching for but didn't know existed. Thank you!
- tepitoperrito 3y agoSee also the C4 model "for visualising software architecture". https://c4model.com/ https://c4model.com/
- maw 3y agoThanks 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.
- mschuster91 3y agoWhat 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.
- 3y ago