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 > [email protected] > my blog | my book | LinkedIn | Delicious | Twitter > On Sun, May 29, 2011 at 8:01 PM, Mark Nottingham <[email protected]> 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 : [email protected] > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp > -- Mark Nottingham http://www.mnot.net/ _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
