20:03:16 <annegentle> #startmeeting
20:03:17 <openstack> Meeting started Mon Jan  9 20:03:16 2012 UTC.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
20:03:18 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic.
20:03:31 <annegentle> #info Agenda at http://wiki.openstack.org/Meetings/DocTeamMeeting
20:03:38 <annegentle> #topic New incoming documents
20:04:10 <annegentle> I've been talking with collaborators about new docs and have been working on one myself with lots of input and reviews
20:04:48 <annegentle> #info New install doc with instructions for Cloud Builders packages at https://github.com/annegentle/openstack-manuals/tree/installdocs
20:05:04 <annegentle> Once I get the testing done, which is going slowly, I'll publish it as a standalone document
20:05:44 <annegentle> I've also been talking to collaborators at HP about putting some docs onto the docs.openstack.org site, and will keep working on it this month
20:05:55 <annegentle> I feel a little bit like I'm just catching up with Diablo and Essex is around the corner.
20:06:12 <annegentle> The third "book" incoming is a Python guide for using the Compute API
20:06:23 <deshantm> nice
20:06:34 <deshantm> I'd love to take a look
20:06:34 <annegentle> #info Working with Devguide.net author for a Python guide for using the Compute API
20:06:59 <annegentle> And lastly, I've got a half-done API Quick Start guide in the openstack-manuals repository
20:07:04 <deshantm> I've started reading through the nova.openstack.org docs
20:07:18 <deshantm> I have a few small edits that I haven't pushed anywhere yet
20:07:19 <annegentle> Ideally the API Quick Start will be linked from api.openstack.org
20:07:37 <annegentle> deshantm: that would be fabulous, edits for that site usually get reviewed and in quickly so feel free to push 'em
20:08:10 <annegentle> As you can see from that list of new incoming docs, still no author for a Xen or XenServer chapter/book.
20:08:37 <annegentle> So we still point people to the wiki page at http://wiki.openstack.org/XenServerDevelopment
20:08:40 <annegentle> Ah well.
20:08:47 <deshantm> what is the write process to turn my etherpad notes into something useful?
20:08:49 <annegentle> Still time to find that author :)
20:09:05 <annegentle> deshantm: just like code, send it through the Gerrit process for review
20:09:26 <annegentle> http://wiki.openstack.org/GerritWorkflow and also http://wiki.openstack.org/Documentation/HowTo
20:09:36 <deshantm> I have this so far, and will continue on it: http://etherpad.openstack.org/openstack-xen
20:09:45 <annegentle> #link http://etherpad.openstack.org/openstack-xen
20:10:01 <annegentle> Yes, I'd like to get that into openstack-manuals when you think it's ready.
20:10:11 <deshantm> I have a lot of content from presentations I've done on the topic to incorporate still
20:10:36 <annegentle> deshantm: yeah, feel free to keep polishing and adding and rounding
20:11:00 <annegentle> #topic Making review diffs easier
20:11:12 <annegentle> I've gotten feedback that it's tough to compare XML doc differences.
20:11:23 <annegentle> So I've started investigating alternatives for the review.
20:11:37 <annegentle> reviewing comparisons between output rather than input, is one idea
20:11:48 <annegentle> #link http://docs.openstack.org/trunk/cs-devguide-diff/content/Overview-d1e71.html
20:12:02 <annegentle> this is an example of a diff done with a tool called deltaxml
20:12:46 <deshantm> that seems nice
20:12:49 <annegentle> Wanted to bring it to this meeting so people could poke at it a bit and see if it's worth exploring further. It is proprietary software, costing about $2000 for the first 3 years with maintenance costs as well, plus the cost of integrating with Gerrit.
20:13:36 <annegentle> So yes, it's costly, proprietary, but it does seem nicer than stuff like this: https://review.openstack.org/#patch,sidebyside,2824,1,doc/src/docbkx/openstack-compute-admin/aboutcompute.xml
20:13:55 <annegentle> I'll shop around the idea to get more input.
20:15:06 <annegentle> ok, on to another topic, source files
20:15:15 <annegentle> #topic Mixing source content
20:15:21 <deshantm> I'm surprised there isn't an open source alternative for the XML diffing
20:15:47 <annegentle> deshantm: good point, we didn't find any (David Cramer and me) but more eyes looking, the better
20:16:24 <annegentle> I know that people like RST and asciidoc and markdown for the simplicity of markup.
20:16:45 <annegentle> Are there any problems with having openstack-manuals have any type of source content?
20:17:08 <annegentle> I'm thinking about putting markdown and docbook in openstack-manuals as source but still outputting html and pdf. Any thoughts?
20:17:58 <deshantm> so in addition to the xml stuff?
20:18:12 <annegentle> deshantm: right, XML for some of the books, markdown for another, and so on.
20:18:26 <annegentle> deshantm: if I could automate it, I suppose going markdown > docbook > output would make sense
20:18:39 <annegentle> for consistency's sake in branding/styling the output
20:19:43 <annegentle> deshantm: making docbook the "interpretation" that goes to output, but still enabling authors to write in what they like
20:19:47 <deshantm> personally i like simpler and the more plain the better, but I think some people that do docs probably like IDEs that do lots of formatting
20:19:50 <annegentle> and reviews may be easier in markdown
20:20:28 <deshantm> so people would have the choice of the markdown or docbook then?
20:20:36 <annegentle> deshantm: I think the fluidity of the content is the pull to XML for me - if you take a look at the openstack-install folder in https://github.com/annegentle/openstack-manuals/tree/installdocs you can see more "topic" authoring - instead of per chapter, writing per "topic" and gluing it all together with xi:includes
20:20:57 <annegentle> deshantm: I don't yet see a good way to cross link Sphinx sites, for example. And a markdown document is quite standalone
20:21:58 <annegentle> Still, I want to enable content creation, ya know?
20:22:10 <deshantm> yeah, the more the better
20:22:22 <annegentle> #topic API quick start and reference page progress
20:22:55 <dwcramer> What about a model where content is initially created in whatever format the contributors prefer and later upcast to the richer format?
20:22:57 <deshantm> i think enabling markdown and seeing if people use it is a low risk option
20:23:32 <annegentle> deshantm: ok, yeah, markdown is good for experimenting with since I have a new guide in markdown
20:23:54 <annegentle> dwcramer: yes, I agree with upcast as a model. Seems like best of "all" worlds.
20:24:09 <annegentle> Sorry if I changed topics too quick :)
20:24:10 <annegentle> So, the mockup site at http://heckj.github.com/api-site-mock/ has been updated with a search box, (yeah!) and some additional content.
20:24:56 <annegentle> I think I have lots of "blessings" on the mockup.
20:25:05 <annegentle> So I feel quite comfortable going forward with it.
20:25:36 <annegentle> I talked at the last openstack-qa meeting about getting help with creating WADLs to form the site content. The QA attendees like the mockup and offered to help.
20:25:45 <deshantm> you know what would be cool on that page... an autocompletion feature. So you type /server/i and it auto completes image for example
20:26:30 <annegentle> deshantm: so it sort of does autocomplete already, just in highlighters in the text below.
20:26:45 <annegentle> deshantm: type "serv" and you see the highlighting below
20:26:56 <dwcramer> I see what he means though...a box for just the paths.
20:27:19 <dwcramer> I'll add a story to the backlog.
20:27:35 <dwcramer> Tab completion makes me happy too.
20:27:42 <deshantm> the other thing that would be nice to see somewhere on this page is an object model
20:27:48 <annegentle> deshantm: yeah makes sense, thanks for adding it dwcramer
20:27:55 <deshantm> just at a high level how things hook together
20:27:56 <annegentle> deshantm: oh, what does that look like?
20:28:22 <annegentle> deshantm: one model site for our mockup was https://dev.twitter.com/docs/api
20:28:30 <deshantm> something like: http://docs.vmd.citrix.com/XenServer/4.1.0/1.0/en_gb/api/docs/html/browser.html
20:28:50 <annegentle> deshantm: oh, how was that put together, do you know?
20:29:18 <deshantm> I don't know actually, but I could ask around to try to find out
20:30:07 <annegentle> deshantm: sure, thanks
20:30:21 <deshantm> my vague recollection is that it was something they were able to automate with Ocaml...
20:30:23 <annegentle> #action deshantm to look for source and toolchain of http://docs.vmd.citrix.com/XenServer/4.1.0/1.0/en_gb/api/docs/html/browser.html
20:30:32 <annegentle> deshantm: automation is good :)
20:30:56 <annegentle> deshantm: with WADL generating the api site, we do get some "automation" but it's not exactly straight from code
20:32:21 <annegentle> We do have a tool for helping with WADL writing, dwcramer do you have that link handy?
20:32:47 <dwcramer> https://github.com/rackspace/wadl-tools/
20:32:53 <annegentle> #link https://github.com/rackspace/wadl-tools
20:33:00 <annegentle> dwcramer: thanks
20:33:02 <dwcramer> Used in conjunction with oXygen.
20:33:17 <annegentle> And oXygen licenses are free to OpenStack contributors
20:33:36 <annegentle> Jay Pipes has agreed to write a WADL for the object-api (Swift)
20:34:08 <annegentle> We have a WADL in review for the image-api, one for compute-api, and several for identity-api (though they're in the Keystone repo)
20:34:26 <deshantm> annegentle: it is autogenerated from source: http://community.citrix.com/display/xs/Exploring+XAPI
20:34:29 <annegentle> So we're nearly set with the content to fill in the mockup and coincide with the Essex release
20:35:16 <annegentle> That's all on the agenda.
20:35:23 <annegentle> # topic Open Discussion
20:37:51 <deshantm> annegentle: https://github.com/xen-org/xen-api/blob/master/ocaml/doc/doc.py
20:37:58 <deshantm> i think that is probably it or some of it
20:38:49 <deshantm> my guess is that it is specific to ocaml that xapi is written in, but it is in python so it may be able to be generalized to work with the OpenStack API
20:40:48 <deshantm> I bet there is a tool that could generate a class diagram given python code
20:41:09 <deshantm> the question is, what does the API look like in code at the moment?
20:41:21 <deshantm> is it a set of inter-related classes?
20:41:32 <deshantm> or is it more stand-alone modules?
20:41:43 <deshantm> it is RESTful
20:41:59 <annegentle> it is RESTful
20:42:34 <annegentle> but I haven't dug into the code well enough to know if it's modules or classes
20:43:02 <annegentle> my attempts to get an auto-generated solution have come up flat... :)
20:43:02 <deshantm> so  maybe it is not necessary, but some high level picture is always useful to get a quick overview
20:43:26 <annegentle> deshantm: yes I like the idea of a diagram somewhere but this site is meant for lookup/reference more than conceptual overview
20:43:37 <annegentle> the API Quick Start definitely should have a diagram though
20:43:45 <annegentle> showing the relatedness of each API to the other
20:43:54 <deshantm> in the end, devs will dig into the details, but if people teaching the API have a picture to point to, it can help their students
20:44:58 <deshantm> just quick impression thoughts is all
20:45:08 <annegentle> deshantm: yes, thanks for that
20:45:19 <deshantm> i don't have anything else
20:45:21 <annegentle> and sorry for my slowness responding, interuptions abound!
20:45:24 <deshantm> (for now)
20:45:33 <deshantm> no worries
20:45:35 <annegentle> ok, that's all I have for now, seems monthly meetings are still okay.
20:45:44 <annegentle> I'll report at tomorrow's team meeting about this one.
20:45:50 <annegentle> but that's it! Thanks for coming.
20:45:54 <annegentle> #endmeeting