Suggest improvements to how the current docs work!

[fatso83]

https://sinonjs.org is where the docs live. We have versioned docs for every major release, (some) interactive examples, and some guides on how to do more elaborate things (like combining Sinon with other tooling to intercept module loading, etc). Still, people end up on StackOverflow or in our issue tracker, for stuff that's been there for a long time. So it's not perfect and multiple attempts at rewriting the docs have happened over the years (including an ongoing effort).

So let's hear from the community: what do you want from the docs site?

There might be stuff missing, functionality that would improve what's already there or things that really are not helping. Please be constructive in criticism: no one is paid to do this.

[fatso83]

The biggest issues I currently see:

• Fake Timers functionality is out of sync
• Not enough examples of how things are supposed to be used. I love the examples we have for Stubs and spies, but it should really extend to all functionality (perhaps as a mandatory part of a PR with new functionality)
• No normative "hints" for "Best practices" or recommendations on how to use the library. For instance, all maintainers wanted to get rid of the Mocks API (since at least 2017, but removing it has not happened) and the quazi-immutable Fakes API was made as a more maintainable and simpler-to-reason about alternative to Spies and Stubs. Still, most existing usage seems to focus on the older APIs (which are quite complicated to maintain and have waaay too big API surfaces).
• Searching is non-existant. One should be able to do in-line searching on API methods, instead of manually looking through categories or (more realistically) googling the site for stuff like "sinon create stub instance"