Mailing List Archive

I really like the idea!

With regards to the grouping - I think I can help and attached is a file. The "xe help --all" command groups all 417+ commands into their logical order. With each release, I have a simple Perl script that extracts this so I can inject it into a Word Document for sharing, knowledge, and my "aging brain".

With regards to the API, I would really like to see examples - based on the SDK and third-party code supported - to give an example of how each call could be used. That may take some time, but would definitely be worth the effort in the long run.

Sincerely,


Jesse Benedict, CCSP, CCA | Sr. Technical Support (10:00 – 19:00 EST) | Citrix Systems, Inc.


-----Original Message-----
From: xs-devel-request@lists.xenserver.org [mailto:xs-devel-request@lists.xenserver.org] On Behalf Of Dave Scott
Sent: Tuesday, January 27, 2015 4:03 PM
To: xen-api@lists.xenproject.org
Cc: xs-devel
Subject: [xs-devel] improving the XenAPI docs

Hi,

I’ve been thinking about how to improve the XenAPI reference[1]. The things I like about the reference are:

- it’s generated from the IDL, so it’s always up to date
- it’s got everything in it

The things I don’t like about the reference are:

- it’s got everything in it… in alphabetical order, rather than in any kind of usefulness order
- the descriptions of fields/ functions are… terse (and often tautologous)
- there are no in-line examples

I’d like to improve the reference by making 2 extensions:

1. I’d like to add tags to each field and function, and allow the docs to be searched by tag (e.g. find all the fields and functions related to “snapshots”) A well-known tag name would be “core” meaning “stuff you need to know” and I propose we either filter for that by default, or at least re-order the elements so we have core first.

2. I’d like to create a sparse file overlay per-API in the xen-api repo. An overlay file — if it exists — would override whatever terse description exists in the raw IDL. The overlay would be written in markdown and would contain paragraphs of description, links and example usages. It would be easy to add an overlay to the repo without breaking the build (i.e. there’s no need to keep all the docs inside the code as well-quoted strings where you have to satisfy the compiler).

Thoughts/ suggestions/ improvements welcome!

Cheers,
Dave

[1] There’s more than one copy on the web, but here’s the one I was looking at: http://xapi-project.github.io/xen-api/index.html

Thanks for raising this, Dave. I think documenting the fields helpfully is important, but examples are key too because that's how people build code in practice.

One more thing I would add: there are too many hash tables (other_config, sm_config, etc.) where the possible (or perhaps I should say, understood) keys and values aren't documented.

Tina thought about this problem a lot and compiled a partial (but large) list of issues: see section 5 of https://info.citrite.net/display/UI/SDK+product+backlog+at+the+end+of+Clearwater.

--
Stephen Turner


-----Original Message-----
From: xs-devel-request@lists.xenserver.org [mailto:xs-devel-request@lists.xenserver.org] On Behalf Of Dave Scott
Sent: 27 January 2015 21:03
To: xen-api@lists.xenproject.org
Cc: xs-devel
Subject: [xs-devel] improving the XenAPI docs

Hi,

I’ve been thinking about how to improve the XenAPI reference[1]. The things I like about the reference are:

- it’s generated from the IDL, so it’s always up to date
- it’s got everything in it

The things I don’t like about the reference are:

- it’s got everything in it… in alphabetical order, rather than in any kind of usefulness order
- the descriptions of fields/ functions are… terse (and often tautologous)
- there are no in-line examples

I’d like to improve the reference by making 2 extensions:

1. I’d like to add tags to each field and function, and allow the docs to be searched by tag (e.g. find all the fields and functions related to “snapshots”) A well-known tag name would be “core” meaning “stuff you need to know” and I propose we either filter for that by default, or at least re-order the elements so we have core first.

2. I’d like to create a sparse file overlay per-API in the xen-api repo. An overlay file — if it exists — would override whatever terse description exists in the raw IDL. The overlay would be written in markdown and would contain paragraphs of description, links and example usages. It would be easy to add an overlay to the repo without breaking the build (i.e. there’s no need to keep all the docs inside the code as well-quoted strings where you have to satisfy the compiler).

Thoughts/ suggestions/ improvements welcome!

Cheers,
Dave

[1] There’s more than one copy on the web, but here’s the one I was looking at: http://xapi-project.github.io/xen-api/index.html
_______________________________________________
Xen-api mailing list
Xen-api@lists.xen.org
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api

I quite like these ideas for improving the XenAPI docs. I think adding tags to the fields and functions so they can be logically grouped is a good idea. We have recently started collecting some docs about the use of the XenAPI on xapi-project.github.io, and have pages for several topics, e.g. http://xapi-project.github.io/xen-api/snapshots.html for snapshots. I think that it is useful to have such topic-level docs to tie things together (with examples) next to descriptions of individual fields and functions. Perhaps we could start by simply augmenting topic pages with an (automatically generated from tags) overview of relevant XenAPI fields and functions, at the bottom of the page or in a sidebar?

Regarding Dave's second point, it would definitely be better to write more detailed descriptions of the XenAPI fields/functions (including code examples and details on the keys/values of map types!!) in something like markdown outside the IDL source code, and integrate these transparently with the existing docs.

Currently, the web-based XenAPI reference at http://xapi-project.github.io/xen-api/ is rendered on the client side by javascript from a JSON description of the XenAPI that comes straight from the IDL. We probably need to switch to a more server side approach to integrate markdown fragments, and the Jekyll stuff from github (which we already use on xapi-project.github.io) may be able to do this. However, the last time I tried it, the IDL JSON file seemed a little too complex for Jekyll to process, so perhaps we need to generate something slightly more straightforward from the IDL.

I'll see if I can knock up a quick prototype.

Cheers,
Rob

> -----Original Message-----
> From: xs-devel-request@lists.xenserver.org [mailto:xs-devel-
> request@lists.xenserver.org] On Behalf Of Dave Scott
> Sent: 27 January 2015 9:03 PM
> To: xen-api@lists.xenproject.org
> Cc: xs-devel
> Subject: [xs-devel] improving the XenAPI docs
>
> Hi,
>
> I’ve been thinking about how to improve the XenAPI reference[1]. The
> things I like about the reference are:
>
> - it’s generated from the IDL, so it’s always up to date
> - it’s got everything in it
>
> The things I don’t like about the reference are:
>
> - it’s got everything in it… in alphabetical order, rather than in any
> kind of usefulness order
> - the descriptions of fields/ functions are… terse (and often tautologous)
> - there are no in-line examples
>
> I’d like to improve the reference by making 2 extensions:
>
> 1. I’d like to add tags to each field and function, and allow the docs to
> be searched by tag (e.g. find all the fields and functions related to
> “snapshots”) A well-known tag name would be “core” meaning “stuff you need
> to know” and I propose we either filter for that by default, or at least
> re-order the elements so we have core first.
>
> 2. I’d like to create a sparse file overlay per-API in the xen-api repo.
> An overlay file — if it exists — would override whatever terse description
> exists in the raw IDL. The overlay would be written in markdown and would
> contain paragraphs of description, links and example usages. It would be
> easy to add an overlay to the repo without breaking the build (i.e.
> there’s no need to keep all the docs inside the code as well-quoted
> strings where you have to satisfy the compiler).
>
> Thoughts/ suggestions/ improvements welcome!
>
> Cheers,
> Dave
>
> [1] There’s more than one copy on the web, but here’s the one I was
> looking at: http://xapi-project.github.io/xen-api/index.html
_______________________________________________
Xen-api mailing list
Xen-api@lists.xen.org
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api