Please elaborate. As the author of said documentation, I'm always open to editorial advice, particularly from end-users since it offers a different perspective from my own.

As for the deprecations...the old methods will probably never go away (they'll be aliased to the the shorter versions). But I'd be remiss in not flagging them as deprecated.

Cheers,
Matt