20:01:28 <annegentle> #startmeeting
20:01:29 <openstack> Meeting started Mon Apr  9 20:01:28 2012 UTC.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
20:01:30 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic.
20:01:31 * lorin1 raises hand
20:01:42 <annegentle> hey lorin1
20:01:45 <annegentle> The agenda is housed at http://wiki.openstack.org/Meetings/DocTeamMeeting, feel free to add to it.
20:02:26 <annegentle> We use "MeetBot" for IRC meeting note-taking, see http://meetbot.debian.net/Manual.html for a reference for the different hashtags used. A couple of our new folks might like to know that. :)
20:03:23 <annegentle> #topic Action items from previous meeting
20:03:35 <kbringard> annegentle: me too
20:03:41 <annegentle> No action items from the last meeting, I apologize for missing the March meeting.
20:03:45 <kbringard> http://www.ihighfive.com/
20:03:48 <annegentle> kbringard: and now you know!
20:04:04 <annegentle> kbringard: oh that's too funny
20:04:16 <kbringard> hah, and now it's in the official minutes
20:04:18 <bcwaldon> and only two clicks away from http://www.insult-generator.org/
20:04:23 <annegentle> #topic Design Summit planning
20:04:39 <kbringard> I feel like we should be able to merge those 2 into some kind of i-facepalm
20:04:47 <annegentle> I have proposed some sessions for the Summit, we have 2.5 hours for the Documentation track. It's Monday morning first thing. Well after a brief kickoff.
20:04:54 <annegentle> kbringard: for sure
20:05:07 <annegentle> #link http://summit.openstack.org
20:05:17 <bcwaldon> #info the track is "Documentation"
20:05:24 <annegentle> #info Summit Documentation track is 2.5 hours Monday morning
20:05:33 <lorin1> Oooh, I like the light-docs idea.
20:05:37 <annegentle> The first proposal is called "Content Sharing and Documentation" which is about how to provide re-brandable content with shared topics.
20:05:52 <annegentle> I'll outline some thinking about how to enable public cloud providers to submit generic OpenStack content while maintaining their own specific content.
20:05:58 <annegentle> #link http://summit.openstack.org/sessions/view/18
20:06:28 <annegentle> Yeah, I liked light-docs too. I changed the title a few times, I wanted to talk about how it should be easy to write and contribute docs, even in ASCIIDoc or Markdown.
20:06:55 <annegentle> I think staying within dev processes is a good thing, but I also believe that we need official manuals and distros are helping out with the DocBook as well. So there's a "WYSWYG" editor camp too, not just ascii-docs.
20:07:23 <annegentle> #link http://docs.openstack.org/api/openstack-compute/programmer/content/ written in Markdown, converted to Docbook
20:07:32 <lorin1> (Sorry, I didn't mean to hijack the agenda there…)
20:07:34 <annegentle> #link http://summit.openstack.org/sessions/edit/96
20:07:39 <annegentle> lorin1: not at all!
20:08:12 <annegentle> lorin1: I've been talking to bcwaldon and vishy and others about how doc changes should be easier
20:08:36 <annegentle> So, the next one is a show-n-tell for the api.openstack.org site.
20:08:40 <annegentle> #link http://summit.openstack.org/sessions/edit/19
20:09:02 <annegentle> But, we're also doing a panel presentation at the Conference about api.openstack.org, so it seems optional
20:09:07 <bcwaldon> annegentle: btw, we cant see those links
20:09:16 <bcwaldon> annegentle: 'edit' is forbidden to non-you
20:09:16 <annegentle> bcwaldon: oh doh.
20:09:19 <lorin1> s/edit/view
20:09:28 <annegentle> lorin1: ok, thanks
20:09:30 <bcwaldon> lorin1: thanks
20:10:12 <annegentle> too bad meetbot doesn't have a link correction method :) Anywho.
20:10:19 <annegentle> I also proposed a "Folsom priority planning" session for docs.
20:10:26 <annegentle> #link http://summit.openstack.org/sessions/view/151
20:10:49 <annegentle> I'll use the Etherpad I sent to the list for the session, but feel free to add to it prior to next week. I added web stats since sending it to the List, too
20:10:56 <annegentle> #link http://etherpad.openstack.org/folsomdocsplanning
20:11:21 <annegentle> That fills up the 2.5 hours we have, but since they're all from me I'd welcome more sessions to choose from and boot one of mine off.
20:12:01 <annegentle> Any questions about the Summit?
20:12:26 <lorin1> Along the lines of light-docs, I'm interested in how to increase the likelihood that somebody who finds an error in the docs will submit a doc bug, even if they don't propose an edit.
20:12:44 <annegentle> lorin1: oh, good idea. there are plenty of questions about how to log doc bugs
20:13:08 <annegentle> lorin1: I do passes through the doc comments and turn them into bugs, but it's manual
20:13:28 <lorin1> annegentle: Yeah, I've talked to people who have read the docs, encountered an error, then googled for the right answer, and don't report the issue.
20:13:46 <annegentle> lorin1: awww…. guh.
20:14:01 <lorin1> annegentle: And I suspect that population includes devs! But I'm more concerned about people who don't even know how to use git, they should be able to submit that there's a problem.
20:14:20 <annegentle> lorin1: yeah. I wonder if we also need a "don't have to use git" process for doc edits
20:15:09 <annegentle> Maybe that's the priority for Folsom, get processes tighter/easier for docs.
20:15:21 <annegentle> the/a
20:15:24 <lorin1> annegentle: That would be nice, but I just want an "unfamiliar with Launchpad" process for reporting a bug. Even if it's just a "send email here for doc problems encountered" in the footer of the docs or somewhere visible.
20:15:34 <annegentle> lorin1: I like.
20:15:47 <annegentle> #info want an "unfamiliar with Launchpad" process for reporting a bug. Even if it's just a "send email here for doc problems encountered" in the footer of the docs or somewhere visible.
20:16:03 <annegentle> lorin1: want to capture that
20:16:07 <annegentle> #topic General documentation status
20:16:17 <lorin1> annegentle: I think you can edit content directly in the github UI, so it's possible we could rig something github-based for quick proposed doc fixes.
20:16:32 <annegentle> lorin1: oo.
20:16:42 <annegentle> I moved a lot of bugs to "Fix Released" today, but there are still plenty of gaps to fill. There are 93 open, 14 in progress. All but 4 of the open ones are confirmed.
20:16:57 <annegentle> I also saw that 41 are reported by me. Hm. :)
20:17:17 <annegentle> So I'd like to take a month to catch up Compute especially to the Essex release. We did this for the Diablo releases and it seemed to work well. Is my memory correct there?
20:18:37 <annegentle> I'm proposing we don't close openstack-manuals "trunk" for another month or so. Does that sound ok?
20:18:52 <lorin1> annegentle: Ahhh. yes, that sounds like a good idea
20:18:57 <lorin1> Oh wait, there's a hashtag for this, right?
20:18:59 <annegentle> #agreed Won't close openstack-manuals "trunk" for another month.
20:19:07 <annegentle> lorin1: yup!
20:19:12 <lorin1> #agreed that's a good idea
20:19:34 <annegentle> There's a lot of merging action to get Compute API extensions onto api.openstack.org. Way to go jakedahn and bcwaldon and a bunch of people!
20:19:55 <bcwaldon> I spent most of my weekend writing extension docs
20:19:57 <bcwaldon> :(
20:20:04 <annegentle> bcwaldon: man I believe it. That's a ton of work.
20:20:19 <bcwaldon> Its a little less painful now after the work you did to figure out sections vs chapters
20:20:21 <annegentle> bcwaldon: I will send you confetti eggs if you want.
20:20:23 <bcwaldon> but still not fun to have to do this after the fact
20:20:30 <annegentle> bcwaldon: yeah.
20:20:41 <annegentle> so take a look at http://api.openstack.org and let us know how it looks
20:20:54 <annegentle> #link http://api.openstack.org now contains Compute API extensions
20:21:10 <bcwaldon> annegentle: one thing to consider is that these extensions are specific to nova
20:21:16 <bcwaldon> annegentle: maybe we need to denote that somewhere?
20:21:35 <lorin1> How many of these extensions have been incorporated into the "nova" CLI? All? None? Or somewhere in between?
20:21:57 <bcwaldon> lorin1: somehwere in between
20:22:15 <annegentle> bcwaldon: yeah trying to figure that scene out too, how do we indicate to users what they have in a given cloud? For now I'm tracking TryStack.
20:22:26 <annegentle> One thing I uncovered last week with some web stats is that docs.openstack.org got 95K visitors in the last month, but api.openstack.org got less than 3K. Trying to figure out how to raise the profile.
20:22:32 <lorin1> bcwaldon: (Where) do we track which features have not yet been exposed through the CLI?
20:22:40 <bcwaldon> lorin1: untracked
20:23:10 <lorin1> bcwaldon: Ah… Whose brains contain this knowledge?
20:23:15 <annegentle> lorin1: good Q
20:23:21 <bcwaldon> annegentle: well we ship with all these extensions (some of which can't really be turned off), and a user is supposed to be able to make a request to see what extensions are deployed
20:23:40 <bcwaldon> lorin1: I wouldnt say its *in* anyone's brain
20:23:57 <annegentle> bcwaldon: yep, what I mean is I'm not promoting adding in non-nova extensions yet.
20:24:05 <bcwaldon> lorin1: people typically write an extension and refuse to document it
20:24:12 <bcwaldon> lorin1: then get around to nova cli when they want to use it
20:24:36 <bcwaldon> annegentle: oh, yes, definitely. I just want it to be clear that these arent extensions to *the* openstack compute api, they're extensions provided with Nova
20:24:51 <lorin1> bcwaldon: Ahhh… Is it generally the case that the author of the extension implements the functionality in the CLI?
20:25:04 <annegentle> bcwaldon: oh ok, good distinction
20:25:08 <bcwaldon> I would say yes, if that implementation does occur
20:25:54 <lorin1> bcwaldon: Gotcha. I'm as guilty as anyone, I implemented one of the extensions but didn't implement in the CLI. But I implemented the extension because it was required to get the main code accepted into nova.
20:25:58 <annegentle> CLI docs are a distinct hole in docs right now
20:26:12 <lorin1> annegentle: Yes, a huge gaping maw of a hole!
20:26:21 <annegentle> lorin1: heh. you said maw.
20:26:43 <annegentle> lorin1: yeah. I should log a doc bug to track it, one for each CLI.
20:27:09 <annegentle> lorin1: documenting them would certainly show why common CLI standards would be helpful :) I was kind of hoping that would happen first :)
20:27:24 <lorin1> lorin1:  The [PENDING] broken links haunt me: http://pypi.python.org/pypi/python-novaclient/2012.1
20:27:29 <lorin1> annegentle: ^
20:27:44 <annegentle> lorin1: I shudder when I see it, and I click it hopefully every time. I'm sad.
20:28:07 <annegentle> #action Anne to log doc bugs for CLI doc maw.
20:28:44 <lorin1> It would be helpful if we could institute some process whereby if you propose new code to a project, and you don't document it, you have to submit a doc bug that says it hasn't been documented yet.
20:28:45 <annegentle> bcwaldon: so what would we say to let people know these are extensions provided by Nova?
20:29:17 <bcwaldon> Just add a note in the copy below 'Compute API Extensions'
20:29:26 <annegentle> lorin1: yeah that's what I was getting at with http://www.mail-archive.com/openstack@lists.launchpad.net/msg09232.html
20:29:44 <annegentle> bcwaldon: sounds good. I'll do that.
20:29:55 <lorin1> annegentle: exactly. Could do this for extensions as well as flags, should be roughly as easy to automate.
20:30:03 <bcwaldon> something like 'The following extensions ship with Nova, but are not required to be deployed for any openstack-compatibile cloud'
20:30:19 <annegentle> #action Anne to create a note describing the extensions on api.openstack.org 'The following extensions ship with Nova, but are not required to be deployed for any openstack-compatibile cloud'
20:30:23 <annegentle> bcwaldon: I like it
20:30:36 <annegentle> bcwaldon: I'll fix the spelling of compatible
20:30:48 <annegentle> Ok, one to open discussion?
20:30:50 <bcwaldon> annegentle: no, I like it the other way
20:31:04 * annegentle snorts
20:31:06 <annegentle> #topic Open discussion
20:31:28 <annegentle> wow, we got through all that in a half hour. Impressive.
20:31:34 <bcwaldon> Could really use somehelp getting through the rest of the extension docs
20:31:51 <annegentle> #info All hands on deck for the rest of the extension docs.
20:31:52 <bcwaldon> #link http://etherpad.openstack.org/nova-ext-docs
20:32:01 <bcwaldon> we've gotten 17/30 done
20:32:17 <annegentle> bcwaldon: wow only six left?
20:32:26 <bcwaldon> 13...
20:32:37 <bcwaldon> ah, some are claimed but I dont know the status of them
20:32:45 <annegentle> bcwaldon: ok, not that I'm bad at math, but I was looking at the Etherpad :)
20:32:45 <lorin1> bcwaldon: I'll take flavorextraspecs,
20:33:00 <bcwaldon> lorin1: awesome, thanks a bunch
20:33:12 <bcwaldon> lorin1: there are several examples in the recent commit history
20:33:12 <lorin1> bcwaldon: np, I did write it, after all. ;)
20:33:26 <annegentle> bcwaldon: I could take server_action_list but would need a reference
20:33:47 <bcwaldon> so I will admit that I've left the more difficult ones
20:34:06 <annegentle> bcwaldon: writerDiane just put a bunch of server statuses in the Compute API book at  https://review.openstack.org/#change,6300
20:34:26 <writerDiane> yes, and I can help with extensions soon
20:34:45 <annegentle> bcwaldon: is a list of actions out there somewheres?
20:34:55 <bcwaldon> annegentle: I can help you figure itout in a bit
20:35:01 <annegentle> writerDiane: awesome, thanks
20:35:06 <bcwaldon> annegentle: its not as clear as one would expect
20:35:19 <annegentle> bcwaldon: you got it. And should I go ahead and merge in the ones from this weekend?
20:35:29 <bcwaldon> annegentle: if they sould good, yes
20:35:35 <annegentle> bcwaldon: ok, great.
20:36:12 <annegentle> Anything else? I'm definitely looking forward to next week.
20:36:27 <lorin1> This is a pipe dream, but I'd like to see some honest-to-goodness usability testing at some point.
20:36:42 <annegentle> lorin1: oh, of the CLI? API? Docs?
20:36:49 <lorin1> Have someone try to set up an OpenStack deployment using docs.openstack.org while somebody observes and takes notes.
20:37:01 <lorin1> annegentle: Docs (+ CLI, effectively)
20:37:05 <annegentle> lorin1: Great idea. I wonder if I can get a Racker to do that.
20:38:06 <lorin1> annegentle: If we had access to a few nodes, we could even do something like this during the summit/conference.
20:38:11 <annegentle> #action Anne to investigate usability testing of Install/Deploy doc
20:38:18 <annegentle> lorin1: oh I like it
20:38:44 <annegentle> lorin1: wonder if we could set up a booth for doc testing
20:39:03 <annegentle> maybe in the dev lounge? I'll ask.
20:39:13 <lorin1> annegentle: Dev lounge would be a good place
20:39:43 <annegentle> I do need to circle back on the install/deploy guide since I think there are still bugs in it
20:40:08 <annegentle> but, Madkiss should be able to get his Quick Start install guide in soon. That'll help with "get going quickly"
20:40:19 <annegentle> The Quick Start install is the Hastexo one
20:40:48 <annegentle> Ok, thanks all for the good discussion.
20:40:54 <lorin1> annegentle: Since we know there are bug issues, and Essex is released, is there some way to inform readers that docs are still being fixed?
20:41:09 <annegentle> lorin1: maybe a "draft" designation would be good?
20:41:21 <lorin1> annegentle: Yes, would be good to have that until it closes.
20:41:41 <annegentle> lorin1: ok, yeah, I think that's the designation for install/deploy still
20:42:02 <annegentle> part of me thinks, well, they'll always be buggy, but another part of me wants a "closure"
20:42:28 <lorin1> "No major known bugs" is a good goal, I think
20:42:42 <annegentle> So I like having a "good as it gets" publish date in a month. Yep, agreed on the "no major known bugs"
20:43:26 <annegentle> Alrighty, enjoy the rest of your day.
20:43:29 <annegentle> #endmeeting