See inline tagged [DFJ]
----- Original Message -----
From: "Mark McLoughlin" <markmc(a)redhat.com>
To: "David Jorm" <djorm(a)redhat.com>
Cc: "rhevm-api" <rhevm-api(a)lists.fedorahosted.org>
Sent: Thursday, April 8, 2010 6:38:08 PM GMT +10:00 Brisbane
Subject: Re: [rhevm-api] REST API docs
Hi David,
On Wed, 2010-04-07 at 22:02 -0400, David Jorm wrote:
Good job, Mark! A couple of comments:
- The current Powershell API docs are command-oriented. Each command
has a section in the docs detailing its syntax and providing usage
examples. The commands are grouped by their functionality. Each of the
classes exposed in the API (as return values from the commands) are
detailed in a separate reference section. What you've generated seems
to be class/object/entity/whateveryoucallit oriented, rather than
command oriented. I don't have a problem with this, but if we were to
move the official docs to this structure it would need wider
discussion. It does seem like the logical way to go based on the way
the new API works, but my understanding is we will also have
Powershell and Linux shell wrapper APIs, which may force a more
command oriented structure for the documentation.
Yeah, I did it this way because, with REST APIs, the important part to
document is the (XML, in this case) representation of the resources
involved
In saying that, though, I think we'll have to do a fair bit of
experimenting to get the right structure for the REST API docs and it
may well turn out that we should put more emphasis on the commands
rather than the resource representations
[DFJ]
Well as I understand it, REST is making each of the verbs/commands standardized across the
resource types. From the documentation perspective, this makes it much simpler, because
you can just document each verb/command once and then have a section for each resource.
That format would work quite well if it's technically feasible for this
implementation.
I guess another thing to think about is that I'm trying to make these
docs more of a technical specification, rather than user documentation.
i.e. this is about documenting the semantics of the API contract which
we will be providing stability guarantees around
Also, each binding/wrapper we may provide (e.g. powershell, linux CLI,
Java, C#, python, perl, etc.) should probably have their own user
documentation
[DFJ]
I agree, we will need a separate guide for each language binding. Is there any PM input at
this stage regarding exactly which languages we want to support?
- The basic syntax of the Powershell API is documented by the
developers using MAML
(
http://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language).
This includes description strings against commands and their
parameters. The MAML is used by Windows to provide online help and
results from the Get-Help command. The DocBook based official
documentation is largely automatically generated from the MAML. Will
there be any analogous internal documentation for the new API which
could serve as a basis for the official docs?
You tell me :-)
The first priority is having a technical specification of the API
contract. If we can write that in a format that would help building
other docs, I'd be more than happy for us to do that.
[DFJ]
So long as it's a standard parser-friendly format, I don't mind what it is. I am
not aware of what the appropriate format would be for this.
Other "documentation" formats which might be of some use to us in
documenting the API contract WSDL/WADL, XML schema/RNG and javadoc, but
I haven't yet figured out the best way to do all or any of that
Cheers,
Mark.