We could generate the documentation from XML files better.
An example is here: http://people.collabora.com/~jonny/protocol/
It has been generated with: https://github.com/jonnylamb/wayland-docs
Especially the cross-references are an excellent feature.
If we are happy with a Python dependency, we should import the generator and integrate it to the big docs both build and content/style wise.
We do at least have cross-references, though they aren't great. The website in general probably needs some help.