20:03:58 <annegentle> #startmeeting
20:03:59 <openstack> Meeting started Mon Jun 11 20:03:58 2012 UTC.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
20:03:59 <writerDiane> Hello!
20:04:00 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
20:04:03 <annegentle> Agenda at http://wiki.openstack.org/Meetings/DocTeamMeeting
20:04:12 <annegentle> #topic Action items from last meeting
20:04:19 <annegentle> First one was Anne to send Beth draft "Learning OpenStack" document
20:04:31 <annegentle> Done - sent to Beth and wabat (Walter) for their review, they'll look at it this week for uses
20:04:46 <annegentle> Second was joe to review bps and cdt product roadmap and update bps accordingly
20:05:05 <annegentle> I'm meeting with Joe Savak tomorrow and I'll follow up.
20:05:14 <annegentle> : put a list of pertinent metadata into the blueprint
20:05:19 <annegentle> not sure who was the colon :)
20:05:24 <annegentle> but I added some
20:05:31 <annegentle> Done - added three items to the blueprint:
20:05:31 <annegentle> git SHA, version of the plugin used to build the particular page, Name or ID of last contributor to the page
20:06:04 <annegentle> I think those would be a great start.
20:06:09 <annegentle> #link https://blueprints.launchpad.net/openstack-manuals/+spec/doc-metadata
20:06:17 <annegentle> last action - Anne to add individual blog posts to Google CSE
20:06:31 <annegentle> Done - added the ones from http://wiki.openstack.org/BloggersTips. For example, if you search for virtualbox on docs.openstack.org, the fourth hit now is a blog post.
20:06:49 <annegentle> I think I'm now two posts behind the list at BloggersTips but I think it's easily maintained.
20:07:11 <annegentle> I can share the CSE credentials with anyone who wants to add more.
20:07:27 <annegentle> and that's all for action items.
20:07:36 <annegentle> #topic Nova config flags reviews
20:08:33 <annegentle> This one went through on trunk: https://review.openstack.org/#/c/8182/ but is still "Review in Progress"
20:08:34 <annegentle> and I'm not sure why. CI team thinks we never did +2 and +1
20:08:43 <annegentle> Same with https://review.openstack.org/#/c/8383/.
20:09:11 <annegentle> Noting it here because there used to be redundant flag listings and those should've cleared them out.
20:09:28 <annegentle> I guess I'll just Review to get those through.
20:10:01 <annegentle> #topic Landing page changes
20:10:18 <annegentle> Switched from /trunk to /essex yesterday and sent a Mailing List post out. Seems well-received and I had gotten plenty of requests for it. :)
20:10:46 <annegentle> So, while last meeting we said we'd wait for divergence between essex and folsom, there was enough uprising requests that I did it at the month mark.
20:10:50 <annegentle> Hope that's okay with everyone.
20:10:58 <annegentle> Ah, benevolent dictatorship.
20:11:23 <annegentle> I'd like to discuss whether to continue to post the Starter Guide on the landing page - it seems redundant now. I really appreciate the work that goes into it. But it's not an "official" doc.
20:11:56 <annegentle> The Starter Guide is the Ubuntu 12.04 document from CSS OSS.
20:12:47 <annegentle> I can ask them to rebrand it as "built for OpenStack" with the CSS OSS logo so that perceptions of it's "officialness" are clear.
20:13:51 <annegentle> #action annegentle to investigate Starter Guide repurposing
20:14:02 <jsavak> \o
20:14:19 <annegentle> hey jsavak
20:14:23 <jsavak> hiya!
20:14:38 <annegentle> jsavak: thought your Monday was a wash for you, thanks for joining!
20:14:52 <jsavak> meeting ended early.Don't tell anyone
20:15:04 <annegentle> one last thought on the landing page switch - I can't figure out why the /essex guides PDF links point to -trunk.pdf file names.
20:15:31 <annegentle> I need to log a bug about it cuz I'm stumped… the pom.xml should be substituting release.name
20:15:43 <annegentle> dwcramer: I'll probably ask you about it after this meeting
20:16:16 <annegentle> any questions on the landing page?
20:16:33 <annegentle> #topic New high availability guide draft
20:16:40 <annegentle> #link https://review.openstack.org/#/c/8139/
20:17:00 <annegentle> Right now it's just an introduction, he has added Pacemaker info into additional reviews set to "Work in Progress"
20:17:16 <annegentle> Please review and comment - I think it'll be a good addition.
20:17:26 <wabat> I agree
20:17:39 <annegentle> wabat: you'd be a good reviewer for that guide
20:17:57 <wabat> I'll probably end up using the guide as well
20:18:10 <annegentle> I'm also hoping it'll help readers understand the "production" guides and the "starter" guides differences.
20:18:17 * annegentle may be asking too much
20:18:33 <annegentle> any questions on HA guide?
20:18:46 <annegentle> #topic Blueprints status
20:19:22 <annegentle> so… operations manual
20:19:36 <annegentle> Notes are at http://etherpad.openstack.org/EssexOperationsGuide
20:19:39 <annegentle> #link http://etherpad.openstack.org/EssexOperationsGuide
20:20:11 <annegentle> There are troubleshooting links we can pull from
20:20:17 <annegentle> #link http://bit.ly/ostsg
20:20:23 <annegentle> #link http://networkstatic.net/2012/05/12/troubleshooting-common-openstack-errors/
20:20:29 <annegentle> but yes these are just bits and pieces.
20:21:11 <annegentle> Still hoping to get at least an Operators Quick Start and Operations Management Practices and Day-to-Day Operations
20:21:15 <annegentle> in time for Folsom
20:21:35 <annegentle> I have shopped the outline around and folks like it
20:21:42 <annegentle> so really it's "just" filling in between :)
20:21:57 <annegentle> the HA guide should help with some of it
20:22:16 <annegentle> any questions? comments? anyone progressing on it?
20:22:53 <wabat> I'm trying to get the day to day stuff going.  I was hoping to get involved in the Trystack admin group but no movement on that yet.
20:23:51 <annegentle> wabat: great - TryStack had a "pregnant" pause when Nati became a dad last week I think :)
20:24:06 <annegentle> wabat: so definitely keep asking how you can get involved and I'll poke at them too
20:24:21 <annegentle> wabat: also jaypipes started a new job
20:24:44 <annegentle> Trystack leads me to another blueprint, a "Deployment template"
20:25:06 <annegentle> I have talked to a wide variety of people on "what is the purpose of this document" and come up with different answers :)
20:25:39 <annegentle> one answer is "document what TryStack does so others can understand a public deployment" the other is "configuration is still too wide and broad what do I do?"
20:25:57 <annegentle> So, a good discussion here is - which do you think the "deployment template" should do?
20:26:34 <jsavak> common out of the box general settings & env variable guide?
20:27:23 <annegentle> jsavak: yeah, that's the original thought, document a couple of deployments
20:27:31 <annegentle> jsavak: no one "wants" out of the box :)
20:27:47 <annegentle> #link http://wiki.openstack.org/RealDeployments
20:27:54 <jsavak> yup
20:28:27 <annegentle> I'm trying to scope this narrowly enough to get done but broadly enough to be useful
20:28:46 <annegentle> "get done" - get something done
20:29:41 <annegentle> rather, "real config info" beyond nova flags
20:29:57 <annegentle> I also hear, "Why" is more generally wanted than "What"
20:31:07 <annegentle> So, I'll keep working on this blueprint, but am still trying to define what doc could be useful. My sense right now is that TryStack needs to get updated to Essex, then we'll have better "why" to document.
20:31:21 <annegentle> third blueprint, API "try-it-out"
20:31:32 <annegentle> I did not end up hiring an intern here at Rackspace for the summer. Sadness.
20:31:46 <annegentle> Four candidates ended up taking other positions not-in-Austin.
20:32:15 <annegentle> But, I do have basic psuedocode and I think here also I want to wait on TryStack to upgrade to Essex.
20:32:57 <annegentle> last blueprint, "metadata in docs" - jsavak let's talk tomorrow about how to work that into a schedule
20:33:09 <jsavak> sure
20:33:12 <annegentle> cool
20:33:15 <annegentle> ok, last topic
20:33:29 <annegentle> #topic Doc tools updates
20:33:52 <annegentle> #info Testing begins on Chinese language documents working with cloud doc tools maven plugin
20:34:02 <annegentle> Setting language to zh should work in PDF builds now.
20:34:13 <annegentle> #link https://bugs.launchpad.net/openstack-manuals/+bug/980580
20:34:22 <uvirtbot> annegentle: Error: Could not parse data returned by Launchpad: HTTP Error 503: Service Unavailable
20:34:28 <annegentle> send us your chinese docbook source so we can test
20:34:29 <chrisfer> oh, cool
20:34:53 <annegentle> the person who logged the bug can hopefully test against her source
20:35:01 <annegentle> chrisfer: yeah!
20:35:16 <chrisfer> I'll let Daisy know
20:35:18 <annegentle> chrisfer: hopefully Daisy got notification on that bug update
20:35:25 <annegentle> chrisfer: better yet, thanks!
20:35:59 <annegentle> another good trick - use <?sbr?> processing instruction for a break in a table cell
20:36:15 <annegentle> that was helpful for all the nova.conf options listings
20:36:48 <annegentle> and then I also learned that Jenkins can't access the plugin builds with -SNAPSHOT for some reason, so I back ported fixes to the stable/diablo branch so Jenkins can build again
20:37:03 <annegentle> not that diablo is getting updated all that often, but it's a good best practice going forward.
20:37:29 <annegentle> the latest clouddoctools plugin version is 1.3.1, and you can test against 1.4.0-SNAPSHOT
20:37:38 <annegentle> any questions on the doc tools?
20:37:42 <chrisfer> annegentle: I sent her a note - she is in class until Weds I think, but maybe someone on the team can test
20:37:57 <annegentle> chrisfer: great, thanks
20:38:09 <annegentle> #topic Open discussion
20:38:25 <annegentle> Anything else on your minds?
20:38:31 <annegentle> (well, that's doc-related)
20:38:51 <ijw> I had a question on api.openstack.org
20:38:55 <annegentle> ijw: sure, go ahead
20:39:01 <ijw> It's a bit of an open question, so bear with me
20:39:42 <annegentle> no worries
20:39:57 <ijw> Is it going to turn into a definitive description of the API, or is it just supposed to be some helpful ideas without being comprehensive?
20:40:16 <annegentle> ijw: I'd like it to document trystack.org, an actual implementation.
20:40:33 <annegentle> ijw: it's hard to define comprehensive… what would that look like to you?
20:41:30 <ijw> The reason I ask is that at the moment it's a bit sketchy when it comes to the posted information.  It lists a set of parameters, and then a chunk of JSON/XML that you can post.  Firstly, I'm not quite sure how the two relate. And secondly, it's not clear if the JSON lists *all* of the possible options that can be used, or whether it just lists one valid set of options.
20:42:14 <annegentle> ijw: for certain the JSON is just one valid set of options… hm, how could the examples be expanded to show more examples?
20:42:37 <annegentle> ijw: ideally the JSON/XML are all working samples - they should be as far as I know. Log bugs if they're not.
20:43:03 <annegentle> ijw: I think a "try it out" implementation might help with getting more possible options - let the user pull more switches, you know?
20:43:50 <ijw> Well, it'd be nice if there was a go-to definitive reference for what the API is, you see - I wasn't sure if the api.openstack.org site was going to be that.  And to be a full document in that sense it has to list all of the available knobs and switches that are there and what they can be set to.
20:44:17 <annegentle> ijw: I'd like it to be the go-to. then we move the "dev guides" into more developer guide mode, instead of "specs"
20:44:34 <annegentle> ijw: want reality :)
20:44:43 <ijw> Yeah, do you want all of reality? ;)
20:45:04 <annegentle> ijw: heh, not really if I only want to limit the scope to TryStack :)
20:45:15 <ijw> Cos I think we need all of reality, somewhere, eventually.
20:45:27 <annegentle> ijw: there's still talk of an extensions registry too, which would be more of reality
20:45:36 <annegentle> ijw: but yes, we NEED reality :)
20:46:12 <annegentle> ijw: thanks for asking
20:46:13 <chrisfer> I think I can see ijw's point
20:46:33 <chrisfer> shouldn't the various fields be fully documented?
20:46:50 <ijw> Indeed, but even docs on the base API would be really helpful.  I'm speaking from a hacking the source perspective here, but the API is where developers and app designers meet and so it would be a good idea to have something that documents it extensively.
20:46:59 <ijw> chrisfer: absolutely, that's the sort of thing I'm talking
20:47:05 <chrisfer> eg. v1.1/{tenant_id}/servers/detail status(optional)
20:47:24 <chrisfer> shouldn't it provide the valid range of values that may be set?
20:47:35 <ijw> And perhaps explain what those values mean...
20:47:37 <chrisfer> that makes sense then
20:47:42 <chrisfer> exactly
20:48:00 <ijw> With apologies, cos that's obviously a lot of work ;)
20:48:04 <annegentle> agree - how do we track what's still missing?
20:48:07 <chrisfer> and if there are constraints (e.g. for date format) then be explicit
20:48:56 <ijw> Well, perhaps the best way to start would be to take a simple GET and a simple-ish POST and document them extensively to see how the whole thing would look.
20:49:29 <ijw> (Emphasis on simple, because e.g. creating a server has a lot of knobs you can twiddle)
20:49:38 <annegentle> #link http://heckj.github.com/api-site-mock/
20:49:43 <annegentle> we started with the above site mockup
20:49:52 <annegentle> I wonder if we can mock up further?
20:50:00 <annegentle> writerDiane may have more details as well
20:50:19 <writerDiane> yes, i'm working on a content model for api refs
20:50:24 <writerDiane> api ref pages
20:50:52 <annegentle> ijw: could writerDiane send you a mockup of the details for "create server" to see if it covers what you're seeking?
20:51:10 <annegentle> ijw: your input is super valuable
20:51:13 <ijw> Yeah, fine with me
20:51:27 <writerDiane> let me know where to send - i can send it to you with mockup for create server
20:51:34 <annegentle> ok, great
20:51:51 <annegentle> #action writerDiane to send mockup to ijw
20:51:53 <chrisfer> writerDiane: this mock-up looks about right
20:52:26 <annegentle> chrisfer: it's pretty low-detail though :) and no content reall
20:52:27 <annegentle> really
20:52:28 <chrisfer> I would again suggest that where applicable, that valid value ranges (or enums) be made explicit in the api doc
20:52:41 <annegentle> chrisfer: ok, that would be a good addition
20:52:46 <chrisfer> well, some include the narrative, which is goodness
20:53:06 <annegentle> ok, any other discussion?
20:53:19 <chrisfer> think each should be accompanied by a narrative that 'splains what it is for, etc
20:53:46 <ijw> Parameters need describing by where they go, too - some are querystring, some in JSON, some in the URL path...
20:53:58 <annegentle> chrisfer: so I think that the narrative belongs in a "Dev Guide" - not on a reference listing page, right?
20:54:06 <annegentle> short content verses long content
20:54:06 <ijw> But yeah, all detail, and all for later.
20:54:26 <writerDiane> yes, i'd say the narrative belongs in dev guide
20:54:49 <writerDiane> my api template covers all that - query parameters, header parms, etc -
20:55:07 <ijw> annegentle, writerDiane: would be nice if the actual bits of information lived in one place and the different guides were generated from it, perhaps; I've no idea if we can do that...
20:56:09 <annegentle> ijw: that's the plan - WADL generates api.openstack.org, then we put the WADL in the dev guide too so it's all one source of truth. So glad you agree. :)
20:56:37 <ijw> I've done this sort of stuff before.  There's nothing quite so horrifying as keeping umpteen Word documents in sync. ;)
20:56:45 <annegentle> ijw: bleeerrrrg.
20:56:46 <annegentle> :)
20:57:33 <annegentle> ok, I'll wrap it up now - thanks all for coming
20:57:38 <annegentle> #endmeeting