6 ms·

"Reading docs top to bottom" is the answer to this frustration. It's strange that people don't think this is something they should do.

Drew_ 5y ago
Agreed but as evident in this post's discussion, developers only have the desire to do so once for <insert-favorite-web-framework> and then the need to do so again for any other framework is understood as the other being clearly terrible and immature.
mirekrusin 5y ago
When people ask me how to improve their programming this is my first advice - speed read docs/stdlib top to bottom and keep writing a lot of little things. It’s amazing how many people choose painful path of learning through osmosis.
- weatherlite 5y ago
  You're right but tbh some docs are kinda horrible. Tried to go through the Spring MVC docs, didn't get far. But maybe I was just being impatient idk.
- jmondi 5y ago
  If you want to make an app from scratch, you must first understand the universe. This is a ludicrous approach for most. Sure, if you learn from reading and love to read technical manuals, go for it. But to imply this is the best way for most to learn is completely ridiculous.
  - wtallis 5y ago
    "Best way to learn" seems too vague to have a productive conversation about. If your goal is to become proficient with a framework, then reading the docs top to bottom is probably a great thing to do, but if you merely want to hack together a one-off project over a weekend then it's probably not worth investing the time to exhaustively learn about all the features and paradigms of that framework.
    - jmondi 5y ago
      Did you learn English by reading the dictionary top to bottom? I’m gonna go ahead and guess that no, you didn’t. You learned English by being surrounded in it and practicing.
      - wtallis 5y ago
        You're being strangely combative in this thread, as though you are personally offended by something. What's your problem, and why are you letting it drive you to make such weak arguments? Do you have some past trauma related to being forced to read, or is it just bad experiences with Rails specifically? It really doesn't take more than a few seconds to figure out why your analogy of learning a language by reading a dictionary written in that language is both stupid and inapplicable here, so I'm not going to try to further address that aspect of your comment (especially since you don't seem inclined to directly respond to anything in my comment).
        jmondi 5y ago
        You’re right, I apologize. You are right that my analogy is stupid on a bunch of different levels. I’ve been surrounded by so many rails fans who use it for every possible problem. “If all you have is a hammer, everything is a nail” was the epitome of what was happening. Then being left with trying to sift through old versions of documentation, trying to figure out what is the “current” way of doing things in rails vs the previous ways, aye yi yi. Rails has definitely left me with a sour taste in my mouth. I’m not saying rails is bad, it is great in so many situations. I’m just saying it is not a silver bullet, and the cult behind it has some real blinders on. I stand by my original argument though that for most people, reading documentation top to bottom isn’t the best way to learn. If it works for you, great.
        4m1rk 5y ago
        People who throw Rails at any problem, either have not maintained a Rails project for long enough or they don't know any other alternative tech.
  - weaksauce 5y ago
    > This is a ludicrous approach for most. there are about 35 guides in the rails guide list and half of those are digging deep into the framework... reading the first 10 of them would get you about 95% of what you really need to know in rails so that you can look up stuff later. hell even just doing the getting started guide walks you through a fairly complete rails application. https://guides.rubyonrails.org/ https://guides.rubyonrails.org/
    - clairity 5y ago
      yah, that's what i did when i first got into rails (~3.0/3.1): read 5-10 of the guides while working through michael hartl's tutorial and reading/watching a number of railscasts (which are dated now, but still have good basic info). i'm working (slowly) on a personal project in rails 7 using all the hotwire with importmaps newness, and so far, it's been so much better than recent rails' diversion into all that node/yarn/webpacker mess.
      - weaksauce 5y ago
        I just put all the essential ones through firefox reader mode and the high end of reading them at what is what an average reader can read at based on the word count and it puts it at 10.31 hours of reading. that's a basically complete understanding of rails that most people don't have. to get 80% there you could probably skim most of them and read the main articles on models, views, and controllers and be done in a few hours. (firefox uses a somewhat naive approach though that just counts words and can't distinguish new code vs. the interesting bits so i'd wager the time is less since there is a lot of repetition in code) it's not a ton of investment compared to how much time it would save you if you use rails later.
  - mirekrusin 5y ago
    You don't need to understand universe, just the tools you'll be using to make an app.
    - desmosxxx 5y ago
      You have to build the universe first.
- calt 5y ago
  Your sibling comment recommends the guides not the full lib docs, and, assuming your chosen technology has both, I'm inclined to agree with them.
sodapopcan 5y ago
I was going to say the same thing and figured someone else already had. People would often ask how I knew so much about rails and, ya, the answer is that I read the guides. They are extremely readable and it doesn't take that long. Like a couple of days. You might be surprised how much is retained by just reading through them, even without actually trying things out as you go. I would like to stress: read the guides, not the docs. Use the docs for reference.
- chowells 5y ago
  I've skimmed the guides. They never contain anything useful. They're just a bunch of recipes. They don't actually document a darned thing. Programming is not regurgitating recipes without understanding. Copilot can do that. Programming is actually understanding both the problem domain and the solution space, and knowing how to find some permutation of elements in the solution space to address anything in the problem domain. The rails guides document about 10% of the problem domain. That's mostly ok, because the problem domain exists in the wider world, and there's lots of documentation elsewhere. The problem is that the rails guides document about 1% of the solution space. And that's an issue, because rails claims to be the solution space. Rails routing is done by passing a block into the framework that's instance_exec'd on... Something. Want to know what, so that you know what API is available to you? Too bad. Here are a list of recipes for the couple most common things you might want to do. Want to do anything more sophisticated, or just understand what your options are? Uh, sorry. Oh, you want to set and read cookies? Here's a recipe for how to read cookies and how to set them with lots of options. You changed how you're setting cookies and now browsers are returning two cookies of the same name and you want to know how to detect and fix this? Silence from the rails guides! (In fairness, the rack documentation actually included enough information to solve that. But it wasn't mentioned in the rails guides about cookie handling. And the rack documentation was a specification, not a guide. It actually tells you what pieces there are and describes their semantics.) And it just goes on and on. Rails has about one hundred options for every one actually mentioned in the guides. In some sense that's a good thing. The guides only give you an incredibly limited set of tools. It's very good that the rest exist. But it means that the guides are a very bad way to learn rails, because they don't give you enough information to solve unforeseen problems yourself, or even enough information to understand code someone else wrote to solve those issues. They put you in the position of hoping someone else anticipated your weird problem and already told you how to solve it. They don't equip you for solving anything weird by yourself.
jmondi 5y ago
Call me crazy, I’d just rather read the relevant section of code I am working on and be able to understand it from there, rather than first having to understand the entire universe.
- givemeethekeys 5y ago
  When working with a framework, it helps to understand the framework. Then, all the individual pieces make better sense. The advantage is that you only have to gain this understanding once.
- MadcapJake 5y ago
  A framework is a social contract, if you will. The framework authors are taking on the onus of some complexity to give you a cleaner and easier to grok codebase. The tradeoff is that you do need to read the guides or you will be diving deep into framework internals whenever you want to understand some app level code.
deleted 5y ago
[deleted]
Jetrel 5y ago
The problem with RoR is that it's an all-encompassing framework. It gives you a huge collection of things you typically don't need — entire major layers like the database are frequently completely irrelevant to projects. This isn't just true of small projects, but can often extend to a large part of a career. One of the grave dangers that older/wiser programmers have learned is to stop trying to pathologically "drink the entire river". Programming has a constant deluge of new frameworks, tools, and publications coming out, and it's easy to fall into the trap of thinking you need to know, well, everything. I know a lot of 'aspiring programmers' who accomplish next to nothing precisely because they waste most of their time reading about programming instead of actually practicing it. It's sadly rather similar to 'aspiring writers', or any other craft — some reading is helpful, but not when it crowds out the actual task it's meant to teach. Life is short, and you have a choice between "actually making things" and "doing prep work for making things". That's all reading the docs is — it's just prep work. It's completely useless unless it parlays into actually accomplishing things. There are semi-rare cases where some language/framework is actually teaching you new fundamentals and is worth deep-reading to gain core skills as a programmer. Haskell broke new ground. Lisp was enlightening. Smalltalk was a worthy historical study. Rust is genuinely changing things. Unfortunately, Rails just isn't special. When I was considerably younger, I used to pathologically do this — I used to buy books on programming, and read them like a school textbook "exam cram". I read entire books on languages (like Perl) that ended up exiting the zeitgeist before I ever did any work in them — and I now have no reason to do so (I feel sorry for Perl, because Larry Wall seems like a cool guy, but perhaps it's a testament to its influence on other languages that it no longer has uniquely redeeming features). I even read books on various applications. Naively, at the time, I looked at learning as a pure, unalloyed good — rather than a dangerous spend of lifetime I'll never get back. I deeply regret wasting that time on that instead of learning a meaningful skill.
- multiplegeorges 5y ago
  > Unfortunately, Rails just isn't special. This is why Rails is so good at what it does. I don't want it to be special. I want it to be mature, work, and allow me to be productive. I have work to do!
ryukoposting 5y ago
It's the single most irritating interaction I have had with a coworker, and I have had it at least once at every job I've ever had. "Hey, thing xyz is super confusing, can you (help me use it|explain how it works|rewrite it so I understand it)?" "Did you read the document I sent? The document (has sample code that does the thing you're trying to do|explains how it works|explains why the simpler approach doesn't actually work in practice)" "...No." It's incredible how some devs can learn 15-20 different programming languages, and completely forget English in the process.
arpyzo 5y ago
This is a fine answer if you're responsible for a small numbers of technologies, otherwise there are far too many "top to bottom" docs to read in a lifetime, let alone the time you have to meet whatever deadline is in front of you. Where it gets even trickier, is that these days nobody is responsible for just a small numbers of technologies. Does your app use the internet? Read about TCP/IP and DNS and other internet technologies top to bottom. Does your app use a database? Read the DB docs top to bottom. How about multiple data stores? Is you app publicly facing? Read about 100 different potential security issues top to bottom. I could go on...
4m1rk 5y ago
Only if the docs were good enough! You always have to look at the source code for most Gems and it's full of unnecessary "magic". I guess Django is a much better alternative because of Python different school of thought

Drew_ 5y ago

Agreed but as evident in this post's discussion, developers only have the desire to do so once for <insert-favorite-web-framework> and then the need to do so again for any other framework is understood as the other being clearly terrible and immature.

mirekrusin 5y ago

When people ask me how to improve their programming this is my first advice - speed read docs/stdlib top to bottom and keep writing a lot of little things. It’s amazing how many people choose painful path of learning through osmosis.

weatherlite 5y ago
You're right but tbh some docs are kinda horrible. Tried to go through the Spring MVC docs, didn't get far. But maybe I was just being impatient idk.
jmondi 5y ago
If you want to make an app from scratch, you must first understand the universe. This is a ludicrous approach for most. Sure, if you learn from reading and love to read technical manuals, go for it. But to imply this is the best way for most to learn is completely ridiculous.
- wtallis 5y ago
  "Best way to learn" seems too vague to have a productive conversation about. If your goal is to become proficient with a framework, then reading the docs top to bottom is probably a great thing to do, but if you merely want to hack together a one-off project over a weekend then it's probably not worth investing the time to exhaustively learn about all the features and paradigms of that framework.
  - jmondi 5y ago
    Did you learn English by reading the dictionary top to bottom? I’m gonna go ahead and guess that no, you didn’t. You learned English by being surrounded in it and practicing.
    - wtallis 5y ago
      You're being strangely combative in this thread, as though you are personally offended by something. What's your problem, and why are you letting it drive you to make such weak arguments? Do you have some past trauma related to being forced to read, or is it just bad experiences with Rails specifically? It really doesn't take more than a few seconds to figure out why your analogy of learning a language by reading a dictionary written in that language is both stupid and inapplicable here, so I'm not going to try to further address that aspect of your comment (especially since you don't seem inclined to directly respond to anything in my comment).
      - jmondi 5y ago
        You’re right, I apologize. You are right that my analogy is stupid on a bunch of different levels. I’ve been surrounded by so many rails fans who use it for every possible problem. “If all you have is a hammer, everything is a nail” was the epitome of what was happening. Then being left with trying to sift through old versions of documentation, trying to figure out what is the “current” way of doing things in rails vs the previous ways, aye yi yi. Rails has definitely left me with a sour taste in my mouth. I’m not saying rails is bad, it is great in so many situations. I’m just saying it is not a silver bullet, and the cult behind it has some real blinders on. I stand by my original argument though that for most people, reading documentation top to bottom isn’t the best way to learn. If it works for you, great.
        4m1rk 5y ago
        People who throw Rails at any problem, either have not maintained a Rails project for long enough or they don't know any other alternative tech.
- weaksauce 5y ago
  > This is a ludicrous approach for most. there are about 35 guides in the rails guide list and half of those are digging deep into the framework... reading the first 10 of them would get you about 95% of what you really need to know in rails so that you can look up stuff later. hell even just doing the getting started guide walks you through a fairly complete rails application. https://guides.rubyonrails.org/ https://guides.rubyonrails.org/
  - clairity 5y ago
    yah, that's what i did when i first got into rails (~3.0/3.1): read 5-10 of the guides while working through michael hartl's tutorial and reading/watching a number of railscasts (which are dated now, but still have good basic info). i'm working (slowly) on a personal project in rails 7 using all the hotwire with importmaps newness, and so far, it's been so much better than recent rails' diversion into all that node/yarn/webpacker mess.
    - weaksauce 5y ago
      I just put all the essential ones through firefox reader mode and the high end of reading them at what is what an average reader can read at based on the word count and it puts it at 10.31 hours of reading. that's a basically complete understanding of rails that most people don't have. to get 80% there you could probably skim most of them and read the main articles on models, views, and controllers and be done in a few hours. (firefox uses a somewhat naive approach though that just counts words and can't distinguish new code vs. the interesting bits so i'd wager the time is less since there is a lot of repetition in code) it's not a ton of investment compared to how much time it would save you if you use rails later.
- mirekrusin 5y ago
  You don't need to understand universe, just the tools you'll be using to make an app.
  - desmosxxx 5y ago
    You have to build the universe first.
calt 5y ago
Your sibling comment recommends the guides not the full lib docs, and, assuming your chosen technology has both, I'm inclined to agree with them.

sodapopcan 5y ago

I was going to say the same thing and figured someone else already had. People would often ask how I knew so much about rails and, ya, the answer is that I read the guides. They are extremely readable and it doesn't take that long. Like a couple of days. You might be surprised how much is retained by just reading through them, even without actually trying things out as you go. I would like to stress: read the guides, not the docs. Use the docs for reference.

chowells 5y ago
I've skimmed the guides. They never contain anything useful. They're just a bunch of recipes. They don't actually document a darned thing. Programming is not regurgitating recipes without understanding. Copilot can do that. Programming is actually understanding both the problem domain and the solution space, and knowing how to find some permutation of elements in the solution space to address anything in the problem domain. The rails guides document about 10% of the problem domain. That's mostly ok, because the problem domain exists in the wider world, and there's lots of documentation elsewhere. The problem is that the rails guides document about 1% of the solution space. And that's an issue, because rails claims to be the solution space. Rails routing is done by passing a block into the framework that's instance_exec'd on... Something. Want to know what, so that you know what API is available to you? Too bad. Here are a list of recipes for the couple most common things you might want to do. Want to do anything more sophisticated, or just understand what your options are? Uh, sorry. Oh, you want to set and read cookies? Here's a recipe for how to read cookies and how to set them with lots of options. You changed how you're setting cookies and now browsers are returning two cookies of the same name and you want to know how to detect and fix this? Silence from the rails guides! (In fairness, the rack documentation actually included enough information to solve that. But it wasn't mentioned in the rails guides about cookie handling. And the rack documentation was a specification, not a guide. It actually tells you what pieces there are and describes their semantics.) And it just goes on and on. Rails has about one hundred options for every one actually mentioned in the guides. In some sense that's a good thing. The guides only give you an incredibly limited set of tools. It's very good that the rest exist. But it means that the guides are a very bad way to learn rails, because they don't give you enough information to solve unforeseen problems yourself, or even enough information to understand code someone else wrote to solve those issues. They put you in the position of hoping someone else anticipated your weird problem and already told you how to solve it. They don't equip you for solving anything weird by yourself.

jmondi 5y ago

Call me crazy, I’d just rather read the relevant section of code I am working on and be able to understand it from there, rather than first having to understand the entire universe.

givemeethekeys 5y ago
When working with a framework, it helps to understand the framework. Then, all the individual pieces make better sense. The advantage is that you only have to gain this understanding once.
MadcapJake 5y ago
A framework is a social contract, if you will. The framework authors are taking on the onus of some complexity to give you a cleaner and easier to grok codebase. The tradeoff is that you do need to read the guides or you will be diving deep into framework internals whenever you want to understand some app level code.

deleted 5y ago

[deleted]

Jetrel 5y ago

The problem with RoR is that it's an all-encompassing framework. It gives you a huge collection of things you typically don't need — entire major layers like the database are frequently completely irrelevant to projects. This isn't just true of small projects, but can often extend to a large part of a career. One of the grave dangers that older/wiser programmers have learned is to stop trying to pathologically "drink the entire river". Programming has a constant deluge of new frameworks, tools, and publications coming out, and it's easy to fall into the trap of thinking you need to know, well, everything. I know a lot of 'aspiring programmers' who accomplish next to nothing precisely because they waste most of their time reading about programming instead of actually practicing it. It's sadly rather similar to 'aspiring writers', or any other craft — some reading is helpful, but not when it crowds out the actual task it's meant to teach. Life is short, and you have a choice between "actually making things" and "doing prep work for making things". That's all reading the docs is — it's just prep work. It's completely useless unless it parlays into actually accomplishing things. There are semi-rare cases where some language/framework is actually teaching you new fundamentals and is worth deep-reading to gain core skills as a programmer. Haskell broke new ground. Lisp was enlightening. Smalltalk was a worthy historical study. Rust is genuinely changing things. Unfortunately, Rails just isn't special. When I was considerably younger, I used to pathologically do this — I used to buy books on programming, and read them like a school textbook "exam cram". I read entire books on languages (like Perl) that ended up exiting the zeitgeist before I ever did any work in them — and I now have no reason to do so (I feel sorry for Perl, because Larry Wall seems like a cool guy, but perhaps it's a testament to its influence on other languages that it no longer has uniquely redeeming features). I even read books on various applications. Naively, at the time, I looked at learning as a pure, unalloyed good — rather than a dangerous spend of lifetime I'll never get back. I deeply regret wasting that time on that instead of learning a meaningful skill.

multiplegeorges 5y ago
> Unfortunately, Rails just isn't special. This is why Rails is so good at what it does. I don't want it to be special. I want it to be mature, work, and allow me to be productive. I have work to do!

ryukoposting 5y ago

It's the single most irritating interaction I have had with a coworker, and I have had it at least once at every job I've ever had. "Hey, thing xyz is super confusing, can you (help me use it|explain how it works|rewrite it so I understand it)?" "Did you read the document I sent? The document (has sample code that does the thing you're trying to do|explains how it works|explains why the simpler approach doesn't actually work in practice)" "...No." It's incredible how some devs can learn 15-20 different programming languages, and completely forget English in the process.

arpyzo 5y ago

This is a fine answer if you're responsible for a small numbers of technologies, otherwise there are far too many "top to bottom" docs to read in a lifetime, let alone the time you have to meet whatever deadline is in front of you. Where it gets even trickier, is that these days nobody is responsible for just a small numbers of technologies. Does your app use the internet? Read about TCP/IP and DNS and other internet technologies top to bottom. Does your app use a database? Read the DB docs top to bottom. How about multiple data stores? Is you app publicly facing? Read about 100 different potential security issues top to bottom. I could go on...

4m1rk 5y ago

Only if the docs were good enough! You always have to look at the source code for most Gems and it's full of unnecessary "magic". I guess Django is a much better alternative because of Python different school of thought