Hi Tom - Yes, sad panda on this guide. Thanks for digging further to find out why.
On Sat, Sep 22, 2012 at 8:46 PM, Tom Fifield <[email protected]> wrote: > Hi, > > Just doing my regular run through the bugs, and at > https://bugs.launchpad.net/openstack-manuals/+bug/961370 I decided to have a > bit more of a look at the OpenStack Identity Developer Guide. > > A quick review: > * Comments (in English and Chinese) are criticising/querying the conceptual > introduction's content, and I note that there isn't really anything much to > tie together the disparate concepts. I'm sure there are diagrams out there > that could help here too. We have a decent diagram, SCH_5002_V00_NUAC-Keystone.png that could be included in the dev guide I believe. > * * There is some good content in parts of section 2, but particularly 2.2 - > response types might need attention. This page appears to have failed its > purpose of detailing that both xml and json are both acceptable for response > and request, with the user comment "is it possible to send json > authentication request to openstack?" Hm, looks like that's just a bug to revise that section. > * Section 3. API Operations provides no more assistance than would be > available on api.openstack.org (However, due to > https://bugs.launchpad.net/openstack-manuals/+bug/1015119 this information > isn't even showing on the API site) > * more user comments: > ** "Keystone authentication and request body parameters (POST v2.0/tokens) > are prerequisite to other admin API requests but astonishingly in not > documented here!" > ** "I was expecting to see set operations in this API. How do you create > tenants, roles, users with the Identity API? Am I missing something huge > somewhere? The pom.xml file that is included with this particular dev guide builds a PDF/webhelp output for each extension, 10 extensions, and a PDF/webhelp for client and a PDF/webhelp for admin calls. There is no CI infrastructure to copy all those files to the docs.openstack.org site. I confirmed the bug 1015119 because it appears the info is missing - but in reality we need a pom.xml that builds either an all-in-one dev guide or a single client and a single admin guide. It's not so much that it doesn't appear on api.openstack.org (or docs.openstack.org/api) but that the doc build is not configured and CI "glue" can not publish what I think should be published. The goal with api.openstack.org originally was to document the TryStack implementation, not to document specs. Since TryStack is for clients not admins, those two commands are the only ones available to TryStack users. One "big picture" item I'd like to keep in mind is that I'd like to do a couple of things: 1. Copy all the "dev guides" into a separate api-site repository to repurpose the specs as true guides. 2. Remove "dev guide" from the title of the spec books in the image-api, identity-api, compute-api, object-api, and network-api repos and replace with "Specification. I've been having lots of discussion on this but little action, my apologies for that. I wanted to get the re-design done so I could think about how this could work going forward. I think it'll be fine. That's where I am with this bug: https://bugs.launchpad.net/openstack-manuals/+bug/933844 Any thoughts on going forward with taking all the current "dev guides" calling them specs, then making real "dev guides?" Thanks Tom for bringing it up! Anne > > Thoughts? > > > Regards, > > > Tom > > -- > Mailing list: https://launchpad.net/~openstack-doc-core > Post to : [email protected] > Unsubscribe : https://launchpad.net/~openstack-doc-core > More help : https://help.launchpad.net/ListHelp -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
