Open Stack

Hi All,

I missed the original thread with the registration to this list, so I will try to summarize my thoughts without history.

First of all, I support the idea of generating the API Reference from the source code as that is the most up to date source of information. On the other hand it makes much easier not just to create the exact document, but keep it up to date, which is unfortunately not true for some of the projects that have their API guide in OpenStack Manuals.

As for the format and placement, I think it can be an experimental process as it is described in the corresponding blueprint. As there are still projects, which have their API documentation in the project tree it shows that it is a viable solution too to put more responsibility on the project teams as opposed to leaving all on the documentation team, which has limited resources compared to the size of OpenStack at the moment.

As I mentioned the documentation, which lives together with the code, it raised a question for me. The API versioning is not always in line with the OpenStack releases neither with the changes on the API. As not every project uses micro versioning or any kind of markup, which shows the changes, it can mean that the v2 version of an API contains less endpoints in let's Juno, than in Kilo. If we document and update the API Reference based only on API versions, then we miss to capture the difference between the functionality covered in the different OpenStack releases. In case of those projects, which maintains their documentation together with the code base this should not be an issue, as the documentation is frozen on the stable branches, when those are cut from master. What do you think about this aspect? Is there a plan to address this issue too?

Best Regards,
Ildiko
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150507/108c26f3/attachment.html>