The corollary for language and API designers: whatever you make easiest is what people will do.
If there is a 'right' way to do something, make that the default or the simplest calling pattern. If there is a new 'right' way, don't route the new way directly through the old way. People will think they're cutting out the middleman by keeping the old calling convention as long as possible.
> If there is a new 'right' way, don't route the new way directly through the old way. People will think they're cutting out the middleman by keeping the old calling convention as long as possible.
It's best if the old way becomes a shim onto the new way --- that shows that the new way works, and encourages moving to the new way -- nobody wants to keep a shim they don't need, and if the new way can do everything, the compatability shim isn't needed.
I'd also like to add that a lot of the time in open source, it's as simple as having the examples be full examples with the error handling needed to use it in a production system. Quite often the examples shown are the "simple" ones, but they leave a lot out. I wish it weren't the case but those are often also pasted into production code.
If there is a 'right' way to do something, make that the default or the simplest calling pattern. If there is a new 'right' way, don't route the new way directly through the old way. People will think they're cutting out the middleman by keeping the old calling convention as long as possible.