api documentation should be written from a user perspective

What I have right now is this:

https://godoc.org/github.com/juju/juju/apiserver/

Which at least documents what is there technically and is quite complete, however it doesn't say how websockets should be used, what responses the api gives, what the methods actually do (typically one sentence that repeats the method name is all that is there), no examples of usage in a programming language (javascript, for instance) are given, etc.

Take this one example:

https://godoc.org/github.com/juju/juju/apiserver/action#ActionAPI.RunOnAllMachines

This method was actually changed in juju2 to be asynchronous, the return is very similar to what was in juju1, but the actions were just... not finished, the doc merely says:

"RunOnAllMachines attempts to run the specified command on all the machines."

Which is not enough to understand what is returned, how I can use it, what inputs are available (those are hidden behind links that are equally terse) what the call structure would be like, and of course that it's async and data needs to be polled to get results (and how to actually do that).

I'm humbly requesting that we take some time to expand the API docs and write them from a user perspective calling the api through websockets. Thanks!