14:06:14 <annegentle> #startmeeting DocTeamMeeting
14:06:15 <openstack> Meeting started Tue Nov 12 14:06:14 2013 UTC and is due to finish in 60 minutes.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:06:16 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:06:18 <openstack> The meeting name has been set to 'docteammeeting'
14:06:24 <annegentle> Here's our Agenda: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting
14:06:46 <annegentle> Let's see, action items from last meeting, all the way back in October.
14:06:52 <annegentle> #topic Action items from last meeting
14:07:48 <annegentle> wow no actions last time, see http://eavesdrop.openstack.org/meetings/docteammeeting/2013/docteammeeting.2013-10-22-13.01.html
14:07:50 <annegentle> whee
14:07:58 <annegentle> #topic Report from the Summit
14:08:24 <annegentle> #link http://lists.openstack.org/pipermail/openstack-docs/2013-November/003252.html
14:08:54 <annegentle> I wrote that post so that we could ensure we all agreed, wish Tom were here so he could discuss his finer points
14:09:41 * chandankumar is going through the link.
14:09:56 <annegentle> I think the doc representation was me, Summer, Tom, and Stephen Gordon, though I also talked to team members who work on docs like Brian Rosmaita for glance, and Edgar for neutron, and cyeoh for the v3 API
14:09:56 <sgordon> annegentle, i was working on something else on the plan but it's going to take a while
14:10:09 <sgordon> some QE guys here and i were mulling the possibility of doing some docs CI
14:10:11 <annegentle> sgordon: the plan will take a while?
14:10:27 <sgordon> by extracting the commands from the XML and then running them via tempest or something of that ilk
14:10:30 <annegentle> sgordon: oh ok, for API docs or for all docs?
14:10:35 <sgordon> i think it would assist with the testing period
14:10:42 <sgordon> i think for targeted installation guide chapters
14:10:53 <sgordon> probably the core bits, choose your own adventure gets a bit hairy
14:10:53 <Loquacity> annegentle: i believe that michael davies is interested on working on some tooling too, has he contacted you?
14:11:07 <annegentle> sgordon: I can't recall the name now, but someone was asking me on Friday about automating install doc testing, I sent him to tripleo, but maybe it's related?
14:11:22 <sgordon> annegentle, probably related
14:11:22 <lorin1> annegentle: Was there any discussion of adding SDK content into the user guide?
14:11:27 <annegentle> Loquacity: hm, that may have been the name?
14:11:35 <Loquacity> he wasn't at summit
14:11:38 <Loquacity> he's on our team
14:11:48 <Loquacity> sorry, by 'our' i mean RCBAU
14:11:58 <annegentle> lorin1: yes, for sure, in Everett's talk, we want to set up developer.openstack.org -- and would definitely like to help you in any efforts around the CLI
14:12:34 <annegentle> Loquacity: ah okay, cool, I can find him...
14:12:46 <lorin1> annegentle: Is there any writeup about that? Or should I just sync with him directly?
14:12:48 <Loquacity> ping me if you need me to get you in touch
14:12:59 <Loquacity> he's mrda on irc
14:13:19 <annegentle> lorin1: yes, https://etherpad.openstack.org/p/icehouse-doc-app-devs
14:13:52 <annegentle> lorin1: we decided the developer.openstack.org should live in a separate repo
14:14:18 <annegentle> lorin1: but the python sdk guide can live in openstack-manuals since it's for users
14:14:30 <annegentle> lorin1: and really only if all this sounds good to you
14:15:01 <annegentle> lorin1: Tom said he'd write a blueprint for it, but you could if you want to
14:15:19 <annegentle> we'll keep api.openstack.org around this release
14:15:24 <lorin1> annegentle: This is all fine by me. But just to clarify, does this mean python sdk guide will remain a separate doc, and not get merged into user guide?
14:16:23 <annegentle> lorin1: I think it could be a series within the user guide, but may need to be separate because one reviewer, a .NET dev, said "irrelevant to me" when reading through it.
14:16:38 <nermina> hi all
14:16:46 <annegentle> lorin1: if I had my druthers, it'd be in the user guide, but I don't know if other sdk devs would think to go there
14:17:01 <annegentle> dianefleming: what do you think about the python SDK info going in the user guide?
14:17:07 <summerlong> o/ nermina
14:17:23 <annegentle> hi nermina
14:17:29 <annegentle> #link https://wiki.openstack.org/wiki/Summit/Icehouse/Etherpads#Tuesday_6
14:17:38 <annegentle> you can read all the etherpads at that link above
14:18:05 <annegentle> I'd like to have some sort of video/hifi meeting online to recap the summit and make sure all questions get answered.
14:18:10 <summerlong> annegentle, am fine to do research on tooling, just won't be free for a few weeks.
14:18:12 <annegentle> I did feel like docs was under-represented.
14:18:18 <annegentle> summerlong: oh goodie.
14:18:19 <dianefleming> i don't think python sdk guide should go into user guide
14:18:38 <annegentle> Yes that was another decision, to have summerlong do a research spike on automating screen captures from Horizon, the dashboard.
14:18:38 <summerlong> +1 that, is a separate audience, or?
14:18:52 <dianefleming> especially if we move cli reference to separate book
14:19:08 <annegentle> summerlong: dianefleming: yes I think it is a separate audience, that's the feedback I have from sdk devs also. I'm just lazy about the maintenance and upkeep of another book, comments, etc. :)
14:19:11 <dianefleming> though we could introduce python in the user guide
14:19:22 <annegentle> oh that reminds me, we did not get further on the ask.openstack.org integration
14:19:34 <annegentle> for API docs,
14:19:36 <annegentle> #link https://etherpad.openstack.org/p/icehouse-api-doc-repos
14:19:57 <annegentle> I really didn't get all the PTLs in one room for that one, but got good input from people there. summerlong was there too.
14:20:22 <annegentle> there's definitely need to keep telling devs that users need user docs for API
14:20:48 <dianefleming> what was the consensus in that meeting?
14:20:57 <annegentle> but there was some questioning of "are we making things worse for block storage and object storage users" and since they are sometimes standalone, I get the concern... just not sure how to address it.
14:21:02 <dianefleming> i mean, what was the consensus from people
14:21:15 <dianefleming> worse by doing what?
14:21:21 <dianefleming> consolidating API information?
14:21:27 <annegentle> dianefleming: questions are at the bottom of that etherpad, such as "Could you just make the dev docs "visible" from the larger document? "
14:21:39 <annegentle> dianefleming: yes, consolidation makes it worse for storage apparently
14:21:59 <annegentle> dianefleming: but, we also have input from the user committee survey that no one knows we have a load balancer API for example
14:22:29 <dianefleming> hmmm
14:22:31 <nermina> there is a category for devs. does the search not bring stuff like that up?
14:22:34 <annegentle> so there's work to be done, consensus was, it won't hurt to have a consolidated guide, and it will point out inconsistencies across APIs, but we will need to consider individual APIs.
14:22:41 <dianefleming> i don't know what it means to make docs "visible" from larger document
14:22:54 <nermina> i'm with you dianefleming
14:22:57 <annegentle> dianefleming: all I could think of was to make sure object storage is easy to find?
14:23:25 <dianefleming> i think the problem with object and block storage is that, their api docs aren't very good at the moment -
14:23:31 <dianefleming> not that they aren't visible enough
14:23:42 <annegentle> dianefleming: they're definitely not user oriented to me
14:23:47 <dianefleming> i think going through the exercise of creating a consolidated API guide will uncover issues -
14:23:56 <summerlong> dianefleming, links to the dev docs instead of including them.
14:23:58 <annegentle> dianefleming: and we have to keep repeating that to the devs, they aren't naturally or automatically empathetic
14:23:59 <dianefleming> also, the exercise of getting the WADLs correct will also fix issues
14:24:04 <annegentle> dianefleming: yes
14:24:29 <dianefleming> we may determine that we need separate guides for APIs after all is said and done but I think we need to start somewhere
14:24:31 <annegentle> dianefleming: also coaching dev teams for a consistent way of documenting the API for users will help. There was a lot of confusion in the session.
14:24:36 <annegentle> dianefleming: so I think this is the right way forward
14:24:45 <annegentle> dianefleming: Exactly. You read my mind faster than I can type.
14:24:45 <dianefleming> hmm - okay - we can talk more later
14:25:05 <annegentle> Let's see, any other reports from the Summit?
14:25:19 <nermina> were the sessions recorded, annegentle?
14:25:22 <annegentle> I nearly died when a cab driver fell asleep at the wheel after the TC dinner. Ugh.
14:25:25 <annegentle> nermina: no
14:25:32 <nermina> wow, annegentle
14:25:34 <lorin1> annegentle: OMG
14:25:35 <dianefleming> you mean you LITERALLY almost died
14:25:40 <Loquacity> heh, i heard about that
14:25:54 <Loquacity> glad you're ok
14:25:55 <dianefleming> did you see the light at the end of the tunnel?
14:25:55 <annegentle> dianefleming: yes. Loquacity: I was so glad mikal grabbed the wheel
14:25:56 <summerlong> nermina, but the etherpad's are pretty faithful to the conversation
14:26:03 <Loquacity> he was very proud of himself ;)
14:26:06 <nermina> thanks, summerlong
14:26:08 <annegentle> dianefleming: I kneeled on the ground when the cab finally delivered us to the hotel. Literally.
14:26:16 <annegentle> Loquacity: LOL
14:26:21 <sdague> true story, I was there
14:26:21 <Loquacity> :P
14:26:22 <dianefleming> ha ha - well, i would've fainted
14:26:38 <annegentle> nermina: yes etherpads are your best bet, and I've also been quizzing people who were in sessions, like the "Future of Design Summits" session
14:27:04 <nermina> very good
14:27:10 <annegentle> Spring is in Atlanta, Fall in Paris. One suggestion from the "future" session was to offset the design portion from the user portion by a day or two
14:27:33 <annegentle> we'll see what changes they can make for Atlanta and Paris, Paris may be too costly to add a day
14:27:55 <annegentle> #link https://etherpad.openstack.org/p/IcehouseFutureDesignSummits
14:28:49 <nermina> "not only red bull, please" lol
14:28:56 <annegentle> nermina: :)
14:29:05 <nermina> moar coffee!
14:29:11 <summerlong> btw, annegentle, I thought 'meet the TC' was quite good.
14:29:28 <annegentle> summerlong: oh thanks!
14:29:56 <annegentle> summerlong: I was asked afterwards why I didn't jump on that first question about diversity on the TC (more representation from Asia was the specifics)
14:30:14 <summerlong> yes, true.
14:30:30 <annegentle> summerlong: people jumped on "get some skin in the game" which I don't really agree with, it's definitely tough to get a leg in when you're sooooo woefully underrepresented. I think we have to do even more outreach.
14:30:50 <sgordon> feels like a wider engagement issue
14:30:56 <sgordon> we obviously have very diverse contributors
14:31:05 <sgordon> but not necessarily engaged in the election process
14:31:20 <sgordon> TC of all bodies in openstack should be a meritocracy
14:31:21 <annegentle> sgordon: hm, good point about election turnout, what was the latest percentage?
14:31:27 <sgordon> not sure
14:31:30 <summerlong> Everyone got an email, right?
14:31:44 <summerlong> How else would you push it?
14:31:44 <sgordon> yeah everyone who is an ATC i think?
14:31:48 <sgordon> or is it all foundation members?
14:32:14 <nermina> i think there should be more info about the nominations
14:32:16 <annegentle> sgordon: ATCs for TC election
14:32:26 <annegentle> nermina: yes our governance is quite complex but all on the wiki
14:32:44 <nermina> right, we get the email about the elections but not nominations
14:32:47 <annegentle> nermina: not that that makes it easy to understand, but it is learnable...
14:32:55 <annegentle> Ok, one more summit item to share:
14:32:57 <annegentle> #link http://www.openstack.org/blog/2013/11/openstack-user-survey-statistics-november-2013/
14:33:23 <annegentle> So the user survey results came back, and finally docs weren't named the most awful thing about openstack! We're number 2! :)
14:33:29 <annegentle> It really was encouraging.
14:33:44 <lorin1> #1 information source!
14:33:55 <nermina> awesome info
14:34:34 <annegentle> And, the user committee can take questions that are specific, for example, I plan to ask if any comments specifically point to documents that are unliked.
14:34:48 <annegentle> Plus we found out they don't know we have a Load Balancer API
14:34:55 <annegentle> I think there are 3 "buried" APIs within neutron
14:35:25 <summerlong> Will the survey be run every 6 months now?
14:35:30 <annegentle> summerlong: yes
14:36:07 <annegentle> The number of deployments nearly doubled in 6 months (84 to 165)
14:36:15 <annegentle> the majority are private cloud
14:36:26 <annegentle> And many are in companies with less than 20 people
14:37:07 <annegentle> The data is kept private, but we can ask specific questions. If you're interested in matching up the user survey with the personas, let me or Dave Neary know.
14:37:08 <annegentle> #link https://docs.google.com/document/d/16rkiXWxxgzGT47_Wc6hzIPzO2-s2JWAPEKD0gP2mt7E/edit?usp=sharing
14:37:14 <annegentle> ^^ that's the persona document
14:37:26 <sgordon> mmmm some of those images got down converted in a way that doesnt really aid readability
14:37:46 <summerlong> I thought it was perhaps my monitor at home.
14:37:49 <annegentle> there's not an exact match on survey-persona
14:37:51 * sgordon squints at the deployment tools image
14:38:44 <annegentle> I think in the blog entry there's a link to the source?
14:38:58 <annegentle> #link http://www.openstack.org/assets/Uploads/Deployments-IceHouse-v1.1.pptx
14:39:03 <sgordon> yeah, a pptx that doesnt load well in libre :)
14:39:08 <annegentle> sgordon: ooo
14:39:12 <annegentle> sgordon: I'll make a PDF
14:39:24 <sgordon> thanks :)
14:39:45 <annegentle> Ok, on to the install guide?
14:39:46 <sgordon> i have saw most of the graphs when it was actually presented but it's useful to have the info as a reference
14:39:49 <sgordon> yes :?
14:39:52 <sgordon> :>
14:39:53 <annegentle> #topic Install guide
14:40:11 <annegentle> I sent a ML post out saying how useful it is to have the install guide done the week of the summit.
14:40:27 <annegentle> I mean, REALLY helpful.
14:40:42 <annegentle> How is it shaping up? Andreas is at a Suse conference this week but hopefully others have a sense of it.
14:41:24 <chandankumar> annegentle, i am fixing the bugs found in the install guide.
14:41:27 <Loquacity> i've noticed a couple of bugs that really are asking for high level changes, so it's probably worthwhile taking a look at the architecture of the book pretty soon
14:41:52 <sgordon> that actually reminds me i think i have some stuff i did on the plane to push
14:41:55 <annegentle> chandankumar: yes, thank you
14:41:58 <sgordon> whoopps
14:42:21 <annegentle> Loquacity: good point. We always get input that they want a controller guide followed by a compute guide, but I don't think that's a good idea for the non-compute projects
14:42:32 <Loquacity> agree
14:42:42 <annegentle> Loquacity: for Swift we could do a proxy guide, a container guide, an object guide, etc.
14:42:54 <annegentle> Loquacity: ok, good. what other overarching input do we have?
14:43:26 <Loquacity> i really want to sit down and do a proper review of the workflows in it, honestly
14:43:35 <annegentle> Loquacity: that would be great
14:43:37 <Loquacity> it's not entirely bad, but i think it's a bit daunting
14:43:42 * Loquacity adds that to her list
14:44:11 <Loquacity> i've kind of been hesitating, since there seems to be rumbling about changing it
14:44:29 <summerlong> but not for icehouse.
14:44:38 <Loquacity> ah, good point summerlong
14:44:48 <annegentle> Loquacity: right, for icehouse, we want to maintain this one
14:45:10 <annegentle> then look at tripleo possible (Tom hates that idea by the way, but sgordon and I are onboard with at least looking at it)
14:45:20 <Loquacity> ok
14:45:31 <sgordon> i think it's worth considering in a J timeframe
14:45:32 <Loquacity> i might take a look with an eye to no major restructuring, then
14:45:33 <annegentle> tom thinks manual install all the way to learn. I do agree partially with that, and that's what I understand from going to user groups, that you have to endure the pain of a manual install to learn.
14:45:43 <annegentle> sgordon: yes, I agree completely
14:45:54 <Loquacity> yeah, i'm coming to the same conclusion, painful as it is ;)
14:45:57 <annegentle> tripleo will have to be documented, not sure it has to be us, but we have to keep it in mind
14:46:13 <annegentle> Loquacity: oh good :)
14:46:38 <annegentle> Question on install guide: shall we keep backporting another month, then let neutron have their way with ml2?
14:47:01 <dianefleming> comment: backports are awful - we need a better way!
14:47:13 <dianefleming> I mean, doing backports is awful, not the actual content
14:48:12 <annegentle> dianefleming: we should be able to automate somewhat
14:48:22 <annegentle> dianefleming: someone mentioned some scripts in the autodoc session
14:48:30 <dianefleming> that would be awesome!
14:48:37 <annegentle> dianefleming: yeah it would be!
14:48:44 <annegentle> dianefleming: but it's only about another month of pain
14:49:00 <dianefleming> oh, and i enjoy pain! (not)
14:50:10 <annegentle> :)
14:50:40 <annegentle> Also, I'm surprised shaunm isn't patching more, anyone hear from him last week?
14:50:52 <annegentle> or maybe he is and I don't see it soon enough?
14:50:54 <Loquacity> he reviewed one of mine at some point, i think
14:50:57 <Loquacity> so he's alive
14:51:02 <annegentle> Loquacity: ok, that's good :)
14:51:08 <Loquacity> ;)
14:51:12 <annegentle> Ok, what's next?
14:51:19 <annegentle> Meeting times!
14:51:24 <annegentle> #topic Meeting times, office hours
14:52:15 <annegentle> Loquacity: if you're willing to run one at those times, it would be great!
14:52:21 <annegentle> Loquacity: I can join most weeks
14:52:23 <Loquacity> actually i volunteered tom to do it
14:52:30 <annegentle> Loquacity: ha ha :) Did he agree?
14:52:44 <Loquacity> considering this seems to have morphed into "lana offered" i guess not ;)
14:52:49 <Loquacity> but either way
14:52:53 <Loquacity> we can argue about it i guess
14:53:00 <summerlong> Is there a reason for moving 13:00 to 14:00?
14:53:17 <Loquacity> yeah, there was a bit of confusion there for us this week
14:53:31 <annegentle> Loquacity: sorry I really thought you were offering, and I'd prefer you to do it, Tom gets too "busy"
14:53:44 <Loquacity> annegentle: yeah, that's cool :)
14:53:51 <Loquacity> i'm on payroll now ;)
14:53:58 <annegentle> summerlong: honestly I think I screwed up due to daylight savings
14:54:05 <summerlong> :D
14:54:11 <nermina> annegentle, now that various things have settled, perhaps we could set up another task list for the install guide. we may have some resources now to test and provide deployment info.
14:54:24 <annegentle> nermina: oh that's nice
14:54:42 <annegentle> Loquacity: and Thank You!
14:54:45 <Loquacity> np
14:54:53 <annegentle> #agreed alternating meeting times
14:55:06 <annegentle> #action Anne Gentle to update ical feed
14:55:39 <dianefleming> cool
14:55:45 <annegentle> #agreed Lana run 1st and 3rd Tuesdays, Anne run 2nd and 4th
14:55:50 <annegentle> Ok!
14:55:55 <annegentle> #topic Open discussion
14:56:04 <annegentle> #link http://aa4698cc2bf4ab7e5907-ed3df21bb39de4e57eec9a20aa0b8711.r41.cf2.rackcdn.com/Deployments-IceHouse-v1.1.pdf
14:56:12 <annegentle> PDF of user survey results for Oct 2013
14:56:26 <sgordon> :D
14:56:28 <annegentle> #link http://www.slideshare.net/openstack/openstack-user-survey-october-2013
14:56:28 <sgordon> thanks
14:56:31 <annegentle> :)
14:56:32 <summerlong> thx
14:57:05 <summerlong> my eyes thank you
14:57:19 <nermina> lol
14:57:50 <annegentle> hee
14:58:07 <annegentle> Couple of things -- would you like a Google Hangout next week to talk about icehouse planning?
14:58:26 <annegentle> And, should we start thinking about another docs boot camp in Feb 2014?
14:58:35 <nermina> yes and yes
14:58:39 <Loquacity> +1 to both
14:58:50 <annegentle> Also, related to the operations guide, I'm thinking about a 2-day "maintenance" sprint in January, lorin1 are you up for that?
14:59:11 <annegentle> #link http://www.openstack.org/blog/2013/11/openstack-operations-guide-now-an-oreilly-early-edition/
14:59:19 <summerlong> Speaking of which, I've got RH people trying to decide on a good ops person to help.
14:59:27 <annegentle> lorin1: I talked to Jon and Everett, they're up for it, need to find Joe too
14:59:29 <nermina> congrats on the o'reilly deal. that was a major feat!
14:59:39 <Loquacity> awesome \o/
14:59:42 <annegentle> summerlong: that would be great. I keep telling Rackspace Private Cloud to get on it also
14:59:48 <annegentle> nermina: thank you!
15:00:15 <annegentle> Oh yeah, I tweeted it out before going on stage for the "Meet the TC" panel, and didn't realize all the epub links were broken. Gah.
15:00:34 <annegentle> Fixed it right after but it took some running around. I should've tested the links better. I literally had the wrong file name in the HTML file. Sigh.
15:00:54 <annegentle> Ok, outta time...
15:01:02 <nermina> it's all agile
15:01:04 <annegentle> Carry on in #openstack-doc. Thanks everyone!
15:01:09 <annegentle> #endmeeting