Right now the documentation is pretty terribly organized. For example, consider the things under the "Users" heading:
/users=> returns Users/users/{ids}=> returns Users/users/{ids}/answers=> returns Answers/users/{ids}/badges=> returns Badges/users/{ids}/comments=> returns Comments/users/{ids}/comments/{toid}=> returns Comments/users/{ids}/favorites=> returns Questions/users/{ids}/mentioned=> returns Comments/users/{id}/privileges=> returns Privileges/users/{ids}/questions=> returns Questions/users/{ids}/questions/no-answers=> returns Questions/users/{ids}/questions/unaccepted=> returns Questions/users/{ids}/questions/unanswered=> returns Questions/users/{ids}/reputation=> returns Reputations/users/{ids}/suggested-edits=> returns Suggested Edits/users/{ids}/tags=> returns Tags/users/{id}/tags/{tags}/top-answers=> returns Answers/users/{id}/tags/{tags}/top-questions=> returns Questions/users/{ids}/timeline=> returns User Timeline/users/{id}/top-answer-tags=> returns Top Tags/users/{id}/top-question-tags=> returns Top Tags/users/moderators=> returns Users/users/moderators/elected=> returns Users/users/{id}/inbox=> returns Inbox Items/users/{id}/inbox/unread=> returns Inbox Items
Under this single heading, there are 12 different return types. In fact, the only thing these methods seem to have in common is that the path starts with "/users", because not all of them even take user ids.
So: can we please get a more sane organization of the documentation page? Something like this would be AWESOME:
Things that produce Users:
/users/users/{user ids}/users/moderators/users/moderators/elected/tags/{tag}/top-answerers/{period}/tags/{tag}/top-askers/{period}
Things that produce Answers:
/users/{user ids}/answers/users/{user id}/tags/top-answers/answers/answers/{answer ids}/questions/{question ids}/answers- ...
Things that produce Questions:
/users/{user ids}/favorites/users/{user ids}/questions/no-answers/users/{user ids}/questions/unaccepted/users/{user ids}/questions/unanswered/users/{user id}/tags/{tags}/top-questions- ...
... etc
Organizing things by what they return and not (seemingly) what the first part of their endpoint path is would make things much easier to find.
status-planned!!!