The various talks I have watched and tutorials I scanned on REST seem to stress something called 'discoverability'. To my limited understanding, the term seems to mean that a client should be able to go to http://URL - and automatically get a list of things it can do.

What I am having trouble understanding - is that 'software clients' are not human beings. They are just programs that do not have the intuitive knowledge to understand what exactly to do with the links provided. Only people can go to a website and make sense of the text and links presented and act on it.

So what is the point of discoverability, when the client code that accesses such discoverable URLs cannot actually do anything with it, unless the human developer of the client actually experiments with the resources presented? This looks like the exact same thing as defining the set of available functions in a Documentation manual, just from a different direction and actually involving more work for the developer. Why is this second approach of pre-defining what can be done in a document external to the actual REST resources, considered inferior?