openstack team mailing list archive

[Mark Nottingham <mnot@xxxxxxxx>]

Thanks, Anne!

On 01/06/2011, at 1:09 AM, Anne Gentle wrote:

> 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 | my book | LinkedIn | Delicious | Twitter
> 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
> 

--
Mark Nottingham   http://www.mnot.net/