openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi Mark -
Thanks for going through and making comments, it's very helpful. I'll have
Jorge address the questions that apply to the architecture decisions, but I
can address these:

A few nits about the document itself, generally --

 - It'd be really nice to have a revision identifier.

Every time the document is revised we edit the date on the front page, so
that is the revision identifier. It's also checked into lp:openstack-manuals
so there are rev numbers associated with it there if you suspect a human
error.

 - In many of the examples, the HTTP response headers and/or request headers
are omitted. IME this often causes confusion and bugs, because developers
don't understand the context of the request or response.

Good point.

 - Finally, could you possibly make the PDF version NOT have grey
backgrounds for all of the examples? It wastes a lot of ink...

Yes, we're figuring out how address this. Our intent is that any OpenStack
contributor should be able to build the PDFs and HTML using Maven, but we're
working towards an open repository and automation that'll let anyone change
the output. In the meantime, I'm able to build PDFs that use no grey
background for examples, and I'll send those your way.

Thanks,
Anne
*Anne Gentle*
anne@xxxxxxxxxxxxx
 my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>
On Sun, May 29, 2011 at 8:01 PM, Mark Nottingham <mnot@xxxxxxxx> wrote:

> <
> http://docs.openstack.org/cactus/openstack-compute/developer/openstack-compute-api-1.1/os-compute-devguide-cactus.pdf>,
> April 25 2011
>
> I've made focussed comments in the online comment facility, as requested.
> Many of the issues I saw had to do with misuse of HTTP status codes or
> re-specification of HTTP functions; please pay particular attention to
> those.
>
> I also have some general comments which don't really belong to any one
> section, so I'll give them here.
>
> Overall, I like the focus on JSON as a default over XML. If anything, I'd
> encourage you to deprecate the XML serialisation and move away from it in
> 2.0. IME, 90% of the interoperability problems in HTTP Web Services are
> XML-related, due to incompatibilities with object bindings with different
> languages, limitations in and complexity of XML Schema (which inevitably
> some people will try to use, even if you don't specify it), and the
> complexity of the XML Infoset itself.
>
> WIth regards to UUIDs -- I'm not sure what the use cases being discussed
> are (sorry for coming in late), but in my experience UUIDs are good fits for
> cases where you truly need distributed extensibility without coordination.
> In other uses, they can be a real burden for developers, if for no other
> reason than their extremely unwieldy syntax. What are the use cases here?
>
> A few nits about the document itself, generally --
>
>  - It'd be really nice to have a revision identifier.
>
>  - In many of the examples, the HTTP response headers and/or request
> headers are omitted. IME this often causes confusion and bugs, because
> developers don't understand the context of the request or response.
>
>  - Finally, could you possibly make the PDF version NOT have grey
> backgrounds for all of the examples? It wastes a lot of ink...
>
> Cheers,
>
> --
> Mark Nottingham   http://www.mnot.net/
>
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>