The problem of the popularity of Ruby and Ruby on Rails - bad documentation
I want to share my thoughts. I read a lot of topics on Ruby, Ruby on Rails, Ruby vs PHP, Python vs PHP. "Every sandpiper praises its own swamp." I believe that this is a purely individual matter - what system or programming language to use, personal preferences, as they say, the taste and color of the comrades still need to be searched. But that's not the point. I know PHP well, I recently started learning Ruby and Ruby on Rails. You know, strangely it sounds, but I like both systems - both PHP and Ruby, maybe even the same. Ruby has its own charms that attract - the power of the language itself, a very clear and concise syntax (if you really go about learning), in PHP - simplicity and the same conciseness of the language. Good systems, good tools, but still Ruby somehow in the role of catch-up. What is wrong here?
And here is what I thought. If Ruby is such an attractive and fashionable development language now, then why does its promotion come with a certain creak? It seems everything is clear and understandable there, but something is clearly not enough. And what is missing is essentially the most important thing - good documentation. I foresee a lot of objections. Yes, it is, but in what form? The official site has several links to docks. Everything seems to be good, with everything in abundance. But! Let me, how can I trust the documentation in which I did not find the description of the elementary method core (!) Method_missing, but in another source - please! Plus, there are no cross references to related, similar methods.
And how it all disagrees with the PHP documentation. Here is a website for you, here you are ALL the documentation - a description of the language, and functions, and cross-references. I remember how I started writing in PHP - I just opened the site and, step by step, I began to explore the language itself first, learning about functions along the way. Just beautiful! For a month from scratch, I wrote a small website without any problems at all.
A completely different picture with Ruby. I approached the study of Ruby more thoroughly - I bought a book, studied everything thoroughly (by the way, I highly recommend Ruby Programming Language, D.Flanagan, Y.Matsumoto), then proceeded to Rails - I found the translation of the book, I studied it in succession. In principle, everything is clear and understandable. But after the end of the reading, there is such a feeling, as if you were briefly explained something (“from the edge of the forest to the forest thicket brought”), and then - “then let it go, mate, walk through the dark forest, and a flashlight and a compass, no, we will not give you - right there and so everything is clear and understandable, we ourselves, calmly, wander around this forest and do not wander, and you will not get lost. ” And nothing, what am I in this "forest" for the first time? ..
')
RoR documentation is simply disgusting - there is no finding what you don’t know about - there is no complete and understandable description of the methods, no description of the parameters of the methods, no examples, no descriptions of classes and their interrelations. Again, parrying the objections, I will say that the descriptions that are - this is just at the level of the primer textbook - described what is in principle understandable. And where to go next? Sources to pick? But, excuse me, I am not a supporter of AvtoVAZ, for example, precisely because these machines should be “finished” almost immediately after purchase. There is a similar situation - to study the car to drive it normally. And what is it for? I buy a car because I want to be a driver, not a car mechanic. I want to use the tool, and not learn it in detail, and besides without instructions - again, the lack of documentation. Many have no idea how their cell phone works, but they use it successfully. There will be interest - I will get into the source code, but for now, this is completely useless to me. Something I don’t remember, that I was offered the functionality of the same PHP on the official website to learn by source. I want to use a programming language, a framework, at what I want at full capacity, and not only at the level of what I was taught in the textbook, to develop and move on, rather than trampling on the spot, picking at the source code. Understand correctly, I don’t care about the details of the work of the tool that I use, so long as it performs all its functions correctly, and I want to know about all these functions, but from the documentation, the “instructions for using the tool”, and not asking anyone Do not crawl on an Internet in search.
As far as I have already learned from my own experience (I have been in the IT industry for more than 20 years), convenient and accessible systems win more often, and having good, convenient documentation is almost half the success, and not those systems where everything is cool for an outsider. not clear, and no one to tell.
Here, in fact, my thoughts. PHP, Ruby, Python, C ++, Java is just one of the ways to communicate with the machine, nothing more. And we are all lucky that we can choose on what to write and how to write. But as long as the system remains little accessible for easy study for any user or programmer, the price of all the coolness that it hides due to the lack of documentation is worthless. There is no need to go far for examples - the popularity and widespread use of any development tool is only a consequence of its availability and the availability of convenient and complete documentation in particular.
At once I will make a reservation that I do not consider the presence of forums or other disparate sources of information for documentation. Any powerful system should possess first of all complete and convenient documentation. And, I think many will agree with me that spending your valuable time on exploring the source code, instead of doing business, is not the most pleasant and rewarding task. It is certainly good to know the source code - such as developing and all that, but I have a lot of things to do, and it would be time for Ruby and Ruby on Rails developers to think about good documentation, otherwise they’ll have such excellent development tools in the tail.
And here is what I thought. If Ruby is such an attractive and fashionable development language now, then why does its promotion come with a certain creak? It seems everything is clear and understandable there, but something is clearly not enough. And what is missing is essentially the most important thing - good documentation. I foresee a lot of objections. Yes, it is, but in what form? The official site has several links to docks. Everything seems to be good, with everything in abundance. But! Let me, how can I trust the documentation in which I did not find the description of the elementary method core (!) Method_missing, but in another source - please! Plus, there are no cross references to related, similar methods.
And how it all disagrees with the PHP documentation. Here is a website for you, here you are ALL the documentation - a description of the language, and functions, and cross-references. I remember how I started writing in PHP - I just opened the site and, step by step, I began to explore the language itself first, learning about functions along the way. Just beautiful! For a month from scratch, I wrote a small website without any problems at all.
A completely different picture with Ruby. I approached the study of Ruby more thoroughly - I bought a book, studied everything thoroughly (by the way, I highly recommend Ruby Programming Language, D.Flanagan, Y.Matsumoto), then proceeded to Rails - I found the translation of the book, I studied it in succession. In principle, everything is clear and understandable. But after the end of the reading, there is such a feeling, as if you were briefly explained something (“from the edge of the forest to the forest thicket brought”), and then - “then let it go, mate, walk through the dark forest, and a flashlight and a compass, no, we will not give you - right there and so everything is clear and understandable, we ourselves, calmly, wander around this forest and do not wander, and you will not get lost. ” And nothing, what am I in this "forest" for the first time? ..
')
RoR documentation is simply disgusting - there is no finding what you don’t know about - there is no complete and understandable description of the methods, no description of the parameters of the methods, no examples, no descriptions of classes and their interrelations. Again, parrying the objections, I will say that the descriptions that are - this is just at the level of the primer textbook - described what is in principle understandable. And where to go next? Sources to pick? But, excuse me, I am not a supporter of AvtoVAZ, for example, precisely because these machines should be “finished” almost immediately after purchase. There is a similar situation - to study the car to drive it normally. And what is it for? I buy a car because I want to be a driver, not a car mechanic. I want to use the tool, and not learn it in detail, and besides without instructions - again, the lack of documentation. Many have no idea how their cell phone works, but they use it successfully. There will be interest - I will get into the source code, but for now, this is completely useless to me. Something I don’t remember, that I was offered the functionality of the same PHP on the official website to learn by source. I want to use a programming language, a framework, at what I want at full capacity, and not only at the level of what I was taught in the textbook, to develop and move on, rather than trampling on the spot, picking at the source code. Understand correctly, I don’t care about the details of the work of the tool that I use, so long as it performs all its functions correctly, and I want to know about all these functions, but from the documentation, the “instructions for using the tool”, and not asking anyone Do not crawl on an Internet in search.
As far as I have already learned from my own experience (I have been in the IT industry for more than 20 years), convenient and accessible systems win more often, and having good, convenient documentation is almost half the success, and not those systems where everything is cool for an outsider. not clear, and no one to tell.
Here, in fact, my thoughts. PHP, Ruby, Python, C ++, Java is just one of the ways to communicate with the machine, nothing more. And we are all lucky that we can choose on what to write and how to write. But as long as the system remains little accessible for easy study for any user or programmer, the price of all the coolness that it hides due to the lack of documentation is worthless. There is no need to go far for examples - the popularity and widespread use of any development tool is only a consequence of its availability and the availability of convenient and complete documentation in particular.
At once I will make a reservation that I do not consider the presence of forums or other disparate sources of information for documentation. Any powerful system should possess first of all complete and convenient documentation. And, I think many will agree with me that spending your valuable time on exploring the source code, instead of doing business, is not the most pleasant and rewarding task. It is certainly good to know the source code - such as developing and all that, but I have a lot of things to do, and it would be time for Ruby and Ruby on Rails developers to think about good documentation, otherwise they’ll have such excellent development tools in the tail.
Source: https://habr.com/ru/post/142586/
All Articles