Better documentation about API navigation and compatibility

This enhances the documentation to try and be clearer about where we do, and
do not, promise users compatibility information, as well as how to use the
navigation tools available.

Signed-off-by: Daniel Pittman <daniel@rimspace.net>