[chrsjxn]

For me, this feels worse than wikipedia using JSON as an example.

JSON isn't a great HTMl representation, and the wikipedia examples are definitely missing details about how the underlying API is used. But extremely simple HTML just feels worse.

Both pages use a bank account as the example, but my actual bank account has dozens of actions available and is certainly modeled in a way that wouldn't be intuitive for people. Which means we've got an example that isn't easily parseable by computers, because we have mixed labels and data in the HTML, and isn't useful for human beings due to how complex real world entities are.

I genuinely can't tell if this is like monads (which are useful, but often poorly explained) or if this is just a bad idea.