Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual.
Then there are even helpful examples beneath that showcase users' experiences and any errata that they've discovered.
I can infer that to_s is probably to_string. But I'm already hit with several new concepts like $, $_ and $\ which aren't clickable, so now it requires work to track down what they mean. The related methods beneath (like puts) are similarly cryptic. A good percentage of the time in search engine results, I click both the Ruby documentation and Stack Overflow links.
I don't remember ever really learning PHP, because I realized quickly into it that it was a thin wrapper fixing any operating system shortfalls, generally leveraging concepts and contextual cues from C, C++ and the shell. Meanwhile Ruby had one of the steepest learning curves I've ever encountered outside of functional programming, even though it's similarly based on Perl and the shell.
So where Ruby is a "convention over configuration" language, PHP is more of an "existing context over surprises" language.
Writing the documentation for a language or framework can reveal these surprises, and over time, improve the tech itself and lead to a better experience.
Also a major overlooked factor in PHP's documentation success is having a specific URL for each function. Some documentation sites use #anchors to jump to spots in a document (ex: boostrap), but it's not good enough. What ends up happening is people search Google for something granular like "mysql concat" and end up on tutorial sites like w3schools. Why? Because the MySQL documentation throws CONCAT() into a giant messy page called "String Functions and Operators": https://dev.mysql.com/doc/refman/8.0/en/string-functions.htm...
Google "mysql concat" and see for yourself. Giant one-page docs are terrible. PHP got it right from the beginning.
Which also results in each function having its own comment section, where users can post further examples and pitfalls with that function. These often end up significantly larger and more informative than StackOverflow.
I have to agree. Php is probably the easiest and moat productive languages I ever learned. The docs were great and the error messages always pointed me im the right direction very quickly. It's no surprise that the language caught on as it did. Ruby, by contrast seemed so hard to learn and I could never see what the advantage was over php so I never had the motivation to push past the difficulties of learning it.
https://www.php.net/<keyword>
For example:
https://www.php.net/echo
Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual.
Then there are even helpful examples beneath that showcase users' experiences and any errata that they've discovered.
Contrast this with Ruby's manual:
https://docs.ruby-lang.org/en/master/ARGF.html#method-i-prin...
I can infer that to_s is probably to_string. But I'm already hit with several new concepts like $, $_ and $\ which aren't clickable, so now it requires work to track down what they mean. The related methods beneath (like puts) are similarly cryptic. A good percentage of the time in search engine results, I click both the Ruby documentation and Stack Overflow links.
I don't remember ever really learning PHP, because I realized quickly into it that it was a thin wrapper fixing any operating system shortfalls, generally leveraging concepts and contextual cues from C, C++ and the shell. Meanwhile Ruby had one of the steepest learning curves I've ever encountered outside of functional programming, even though it's similarly based on Perl and the shell.
So where Ruby is a "convention over configuration" language, PHP is more of an "existing context over surprises" language.
Writing the documentation for a language or framework can reveal these surprises, and over time, improve the tech itself and lead to a better experience.