This is an interesting perspective if I'm understanding you correctly.
Are you saying that Rails is "magical" because it is often presented to new people that way, but if it were more often presented as "a bunch of Ruby code that does a bunch of stuff, please do go look and see how it does that stuff", it would not be "magical" without being implemented or documented at all differently?
Kinda, if I'm making sense of your question :) Did my article make sense? I'd love to hear what you thought of it. There's basically two halves:
1. Under-promising. I'll quibble with the word 'documented'. Part of the problem is that frameworks market and position themselves with their prose to be hermetically sealed containers offering wondrous features. That's part of their documentation. That we do need to change, IMO.
2. Over-delivering. It's not enough to be open source, and it's not enough to just say, "please do go look and see how it does that stuff." Software is in the stone ages because we aren't able to actively help newcomers get quickly up to speed on our code. We need to think about the big picture of a codebase, and how it's presented to others.
Are you saying that Rails is "magical" because it is often presented to new people that way, but if it were more often presented as "a bunch of Ruby code that does a bunch of stuff, please do go look and see how it does that stuff", it would not be "magical" without being implemented or documented at all differently?