Release Notes Examples Need Work

rubyonrails-docs
1

I have been programming regularly in Ruby, and primarily Rails, since 2006.

Yet I found the examples shown on the 4.1 Release Notes page to be cryptic and not very informative.

Remember that not everybody who reads the release notes page is on the dev team. Examples should be made clear and basic, and at least somewhat understandable to those who are relatively new to Rails.

In my opinion, the examples assume too much context. It should be spelled out better, even if that means a much longer page. Many open source projects give documentation short shrift, to the detriment of us all. Don’t let Rails be one of them.

2

Release notes are not supposed to be totally friendly to newcomers, they are deltas over existing software and are allowed to assume some context.

If someone doesn't know the feature a certain version is evolving, release notes are not the place to explain the base feature, rather they have to explain the delta assuming you know the feature (if you don't the place to look for that information is the documentation).

That said, if you see places where they can be improved please feel free to propose a patch.