On the state of documentation

[Stewart Smith]

Hi all,

thought I'd try and contribute my thoughts here, as a consumer of
OpenBMC rather than a developer on it.

The message has long been that the REST API is what should be used to
interact with the BMC, and as such we now have a lot of tooling that
does just that (and we're not the only ones).

Over the past $months, it's been frustrating (to say the least) that
there hasn't been any good documentation of this API.

Indeed, If I look at the API on the "Rusty's API Scale" of usability:
http://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html
http://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html
It's all pretty high on the negatives, although it does vary on what
specific API you're looking at.

A lot of the negative scoring here is due to a near complete absence of
documentation. Most things that we use have ended up being documented
either in the implementation (which may or may not allow you to use it
correctly), or by some random thread on an IBM internal slack channel.

Additionally, this issue and PR has come up:
"Remove org.openbmc.* from REST server"
https://github.com/openbmc/openbmc/issues/2378
https://gerrit.openbmc-project.xyz/#/c/7422/

This morning, I took a stab at going through the documentation and
working out what this means for current documentation:
https://gerrit.openbmc-project.xyz/#/c/7916/

In short: it's not good. There is now no longer documentation even
describing how to turn the host on and off.

If the above "remove org.openbmc.* from REST server" is merged, there
will be *ZERO* documentation on how to turn the host on and off - which
is about the most simple thing you want to do with a BMC.

Is there a plan to attack this?

IMNSHO I'd like to see a standard interface be "the way" to talk to
OpenBMC based systems, something like RedFish, which I noticed there was
the start of some work on here: https://gerrit.openbmc-project.xyz/#/c/7786/

But even if RedFish/IPMI became *the* way externally, the internal APIs
(as in, d-bus APIs) could probably also do with some love.

My initial stab at helping with that is:
https://gerrit.openbmc-project.xyz/#/c/7923/
but even then, that very same API raises a lot of other questions that I
haven't addressed - and even in that pull request, I've made a bunch of
sweeping statements binding the OpenBMC developers to certain API
stability constraints.
-- 
Stewart Smith
OPAL Architect, IBM.