Better API docs

[jimaek]

I'm not very happy with our API docs, most other projects have much nicer ones. Here are some relatively simple ideas to improve them

1. Switch to something like https://github.com/scalar/scalar
2. Link to the demo page, the Slack chat was not the first time it helped, I often email it to devs working on an integration and they all find it very useful. Mention it in an obvious way
3. Update limits table to include missing data
4. Consider improving the content itself to make things more clear

Issues people had that are worth addressing e.g. making more obvious:

• How long it is expected for a measurement to be available
• Are they public for everyone
• Not clear how to separate probe failures from target failures
• Unclear why some probes return DNS resolvers and others not
• Too many questions about the 500 tests per hour limit. Some thing it's a hard limit of testing in general, like an anti-abuse system. Others think their donated credits are used first and the free ones after that.

[MartinKolarik]

Too many questions about the 500 tests per hour limit. Some thing it's a hard limit of testing in general, like an anti-abuse system. Others think their donated credits are used first and the free ones after that.

I think this was addressed by the recent update; it says exactly that:

Also, not sure what other missing limits you have in mind.

[jimaek]

I think this was addressed by the recent update; it says exactly that:

It's still somewhat unclear I think. It doesn't clarify it's not a hard limit and its basically free credits. In the new theme it could be highlighted in a better way.

[jimaek]

Another 2 emails from devs asking how to increase the limit above the 500 per hour. Too many devs think that's a hard limit and not just the free limit. Something to address for sure

[jimaek]

Instead of switching the template can we do something like this? https://stitch.withgoogle.com/preview/15255474544506003704?node-id=980d82f862a945988f984ca2b796404e&raw=1

• A bit better top nav menu
• Better looking examples on the side
• Small changes to sidebar