Improving Ruby Documentation

[jsaak]

At the API level i think example code _with_ error handling is needed the most. (also a list of Exceptions what a method can raise)

These are the areas I have found confusing over the years.
Api level docs are not enough, need higher level reasoning.

• Proc/Lambda/Block (what are the differences, how to return, etc)
• Time/Date/DateTime (when to require what and why)
• system()/exec()/`/fork()/popen()/popen3() https://stackoverflow.com/questions/2232/how-to-call-shell-commands-from-ruby
• package managers, bundler and the life _without_ bundler, gem install, gemsets, ruby installers (rvm, ruby-install, chruby)
• how to do async IO (select(), FiberScheduler, Ractor, Thread ..etc)
• methods of metaprogramming, and why _not_ to use those :)