Right now [the documentation is pretty terribly organized](https://api.stackexchange.com/docs).  For example, consider the things under the "**Users**" heading:

- `/users` => returns [Users][user]
- `/users/{ids}` => returns [Users][user]
- `/users/{ids}/answers` => returns [Answers][answer]
- `/users/{ids}/badges` => returns [Badges][badge]
- `/users/{ids}/comments` => returns [Comments][comment]
- `/users/{ids}/comments/{toid}` => returns [Comments][comment]
- `/users/{ids}/favorites` => returns [Questions][question]
- `/users/{ids}/mentioned` => returns [Comments][comment]
- `/users/{id}/privileges` => returns [Privileges][privilege]
- `/users/{ids}/questions` => returns [Questions][question]
- `/users/{ids}/questions/no-answers` => returns [Questions][question]
- `/users/{ids}/questions/unaccepted` => returns [Questions][question]
- `/users/{ids}/questions/unanswered` => returns [Questions][question]
- `/users/{ids}/reputation` => returns [Reputations][reputation]
- `/users/{ids}/suggested-edits` => returns [Suggested Edits][suggested-edit]
- `/users/{ids}/tags` => returns [Tags][tag]
- `/users/{id}/tags/{tags}/top-answers` => returns [Answers][answer]
- `/users/{id}/tags/{tags}/top-questions` => returns [Questions][question]
- `/users/{ids}/timeline` => returns [User Timeline][user-timeline]
- `/users/{id}/top-answer-tags` => returns [Top Tags][top-tag]
- `/users/{id}/top-question-tags` => returns [Top Tags][top-tag]
- `/users/moderators` => returns [Users][user]
- `/users/moderators/elected` => returns [Users][user]
- `/users/{id}/inbox` => returns [Inbox Items][inbox-item]
- `/users/{id}/inbox/unread` => returns [Inbox Items][inbox-item]

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.

  [user]: https://api.stackexchange.com/docs/types/user
  [answer]: https://api.stackexchange.com/docs/types/answer
  [badge]: https://api.stackexchange.com/docs/types/badge
  [comment]: https://api.stackexchange.com/docs/types/comment
  [question]: https://api.stackexchange.com/docs/types/question
  [privilege]: https://api.stackexchange.com/docs/types/privilege
  [reputation]: https://api.stackexchange.com/docs/types/reputation
  [suggested-edit]: https://api.stackexchange.com/docs/types/suggested-edit
  [tag]: https://api.stackexchange.com/docs/types/tag
  [user-timeline]: https://api.stackexchange.com/docs/types/user-timeline
  [top-tag]: https://api.stackexchange.com/docs/types/top-tag
  [inbox-item]: https://api.stackexchange.com/docs/types/inbox-item