openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

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 <fifieldt@xxxxxxxxxxxxxx> 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     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp