@cgrf well, thanks for the feedback anyway. As for structure, I do have it in chapters. So the technical stuff is separated from other things, and the whole thing starts with how to actually use it, and the theory goes last for those interested. I could split it into separate pages but I feel that just fragments it.
As for the use cases, they are also split and I am not sure how to simplify them further.
As for what version they work with, the current setup is that there are always two versions. One for the most current release here: https://www.mysensors.org/apidocs/index.html
The other is for the beta releases (development branch), which is always bleeding edge here: https://www.mysensors.org/apidocs-beta/index.html
The version is currently to the git sha. But I have a pull request open that will make further releases show a version number instead which better link the documentation to a human readable version.
It will also update the security part of the "library customization" chapter a bit.
