api documentation should be written from a user perspective

Bug #1596071 reported by David Britton
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Canonical Juju

Bug Description

What I have right now is this:


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:


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!

David Britton (dpb)
description: updated
Changed in juju-core:
status: New → Triaged
importance: Undecided → Medium
tags: added: api docs usability
Curtis Hovey (sinzui)
affects: juju-core → juju
tags: added: helptext
Revision history for this message
Canonical Juju QA Bot (juju-qa-bot) wrote :

This bug has not been updated in 2 years, so we're marking it Low importance. If you believe this is incorrect, please update the importance.

Changed in juju:
importance: Medium → Low
tags: added: expirebugs-bot
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.