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