13:01:15 <annegentle> #startmeeting docteammeeting
13:01:16 <openstack> Meeting started Tue Oct 22 13:01:15 2013 UTC and is due to finish in 60 minutes.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
13:01:17 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
13:01:19 <openstack> The meeting name has been set to 'docteammeeting'
13:01:23 <annegentle> The agenda is at http://wiki.openstack.org/Meetings/DocTeamMeeting, feel free to add to it.
13:01:39 <annegentle> Most of you know this, We use "MeetBot" for IRC meeting note-taking, see http://meetbot.debian.net/Manual.html for a reference for the different hashtags used.
13:01:56 <EmilienM> hello :) and happy birthday Anne !! (joyeux anniversaire in french)
13:02:00 <NickChase> Hey, happy birtheday, Anne!
13:02:02 <annegentle> #link https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting
13:02:10 <annegentle> Thanks NickChase and EmilienM!
13:02:15 <chandankumar> annegentle, Happy Birthday ANNE. :)
13:02:36 <dguitarbite> happy b'day ANNE
13:02:39 <annegentle> :)
13:02:50 <annegentle> So I think all the Actions should be easy to run through.
13:02:54 * annegentle shaunm_ testing nova-network on Fedora, DONE
13:03:12 <annegentle> At least I think so. Shaun's not here
13:03:26 * annegentle AnneGentle to email the openstack list asking for help, DONE -- got a good response too!
13:03:31 <annegentle> And that was it for actions
13:04:07 <annegentle> Next up
13:04:10 <annegentle> #topic Bug report, DocImpact state
13:04:39 <annegentle> So, I think that dianefleming has been moving havana bugs to icehouse when they apply to icehouse, like v3 Compute API
13:04:55 <dianefleming> yes
13:05:03 <annegentle> There are a lot of bugs and comments for the install guide, which are havana.
13:05:15 <annegentle> #link https://bugs.launchpad.net/openstack-manuals/+milestone/havana
13:05:40 <annegentle> But I don't think our havana numbers will go down noticeably until say XenAPI gets revisions, that kind of grouping is what I'm seeing.
13:05:41 <dianefleming> i can  take on moving all the bugs if you want (havana bugs) and noting to backport to havana
13:05:47 <AJaeger> Should we discuss the Install Guide as extra topic?
13:06:11 <annegentle> dianefleming: I think what the code projects do is move them wholesale through the Launchpad API, but I don't yet know exact details
13:06:20 <annegentle> dianefleming: so we might save you some clicks if we can figure out the API way?
13:06:27 <dianefleming> awesome!
13:06:30 <annegentle> AJaeger: yes let's have the install guide as another topic
13:06:39 * AJaeger adds it to AGenda
13:07:10 <annegentle> I also think there are keystone doc bugs and vmware doc bugs
13:07:15 <annegentle> I sense that there are big groups of doc bugs
13:07:26 <annegentle> Just noting that, not saying we have to take a specific action
13:07:37 <annegentle> AJaeger: perfect, thanks
13:08:37 <annegentle> There are definitely doc bugs that could be easily picked up, triaged, and might already be fixed, such as Nova CLI has new IP parameter, neutron-debug is not documented, Add swift_store_ssl_compression param, those all seem fixable
13:08:48 <annegentle> So my note on the bug report is to keep fixing doc bugs :)
13:09:01 <annegentle> And, I've been entering doc bugs for the install guide when comments indicate a doc bug
13:09:08 <annegentle> Anything else on doc bugs?
13:09:27 <annegentle> Ok, next topic
13:09:41 * annegentle hits refresh
13:09:46 <annegentle> #topic Install Guide
13:10:02 <annegentle> AJaeger: just saw your new bug from your QA input, that's good to get, want to discuss?
13:10:17 <annegentle> #link https://bugs.launchpad.net/openstack-manuals/+bug/1243131
13:10:20 <uvirtbot> Launchpad bug 1243131 in openstack-manuals "Comments on Neutron" [High,New]
13:10:48 <AJaeger> Just an info: I have one of our QA guys going through the document - and sending me emails with things that are wrong...
13:11:32 <annegentle> AJaeger: that's great.
13:11:54 <AJaeger> I see a lot of patches for the Install Guide and would ask to review these quickly to avoid conflicts
13:11:55 <annegentle> The comments have been very useful too
13:12:01 <annegentle> As is the doc bug link
13:12:04 <NickChase> they seem like pretty straightforward corrections.
13:12:13 <AJaeger> Should we mark these patches in a special way?
13:12:15 <NickChase> very helpful
13:12:16 <annegentle> NickChase: yeah some markup stuff, some duplications
13:12:19 <AJaeger> The doc bug link is GREAT!
13:12:30 <annegentle> AJaeger: Just with backport: stable/havana
13:12:34 <annegentle> AJaeger: yes!
13:12:50 <AJaeger> I meant something like say "Install Guide" in the commit header...
13:12:50 <NickChase> LOVE that you get the source file where the problem is
13:12:53 <annegentle> AJaeger: yes I agree on reviewing install guide patches quickly, and backporting as soon as they merge
13:13:08 <annegentle> AJaeger: oh that would be good, sorry I hadn't used that the last few patche
13:13:10 <annegentle> patches
13:13:21 * AJaeger didn't use it either
13:13:41 <annegentle> #agreed Use Install Guide in the commit header when patching the Install Guide so that reviewers can make those patches a priority
13:14:08 <annegentle> Anyone else have input on install guides? I wish Shaun was online
13:14:23 <annegentle> I don't know when his contract is up
13:14:51 <nermina> hello all
13:14:51 <annegentle> Does anyone else want to be a moderator on install guide comments? For Ubuntu it's me, EmilienM, Tom, and Lorin I think.
13:14:56 <annegentle> hi nermina!
13:15:07 <nermina> sorry, two different school dropoffs
13:15:27 <annegentle> I'm a little irritated with Disqus for forcing loging to see the feed of comments on a particular guide
13:15:37 <annegentle> I hope to replace Disqus with ask.openstack.org Real Soon Now.
13:15:44 <dianefleming> yes!
13:15:46 <annegentle> loging should be logging in
13:15:54 <dianefleming> what's the blocker from doing it asap?
13:16:01 <AJaeger> with the bug links, we could also remove everything...
13:18:40 <annegentle> sorry just got interrupted in person :)
13:18:52 <NickChase> How dare they. :)
13:19:02 <annegentle> dianefleming: it's really just getting that redesign done, from Todd Morey
13:19:19 <dianefleming> ok!
13:19:44 <koolhead17> hi all
13:19:56 <annegentle> I've got a blueprint now for the redesign: https://blueprints.launchpad.net/openstack-manuals/+spec/redesign-docs-site
13:20:02 <annegentle> hey koolhead17
13:20:03 <koolhead17> EmilienM: thanks for the tip. birthday wishes annegentle
13:20:12 <annegentle> and I've asked Todd if he can have a demo ready by the summit
13:20:15 <annegentle> koolhead17: hee hee thanks!
13:20:26 <koolhead17> annegentle: awesome!!
13:20:43 <annegentle> koolhead17: yes I have high hopes, Todd is incredible
13:21:22 <annegentle> Ok, I definitely want to emphasize speedy attention on the install guide bug reports
13:21:40 <annegentle> Let's move the agenda around a bit to give sarob a chance to join in
13:21:44 <annegentle> #topic Backports
13:22:08 <AJaeger> I put this on the agenda since dianefleming did a great rework of one my backports.
13:22:11 <annegentle> We have a nice addition/explanation for backports on the wiki now
13:22:14 <annegentle> AJaeger: oh nice!
13:22:32 <AJaeger> I'm under the impression that backports should be cherry-picks (plus resolving conflicts) only
13:22:36 <dianefleming> phew! glad it was ok @AJaeger
13:22:39 <annegentle> #link https://wiki.openstack.org/wiki/Documentation/HowTo#Git_commit_messages_and_backports
13:22:46 <AJaeger> So, I split out dianefleming'S patch into a separate patch.
13:22:58 <dianefleming> thanks!
13:23:04 <annegentle> AJaeger: yeah, that makes sense to me as a reviewer, otherwise the merging might get too hard
13:23:08 <AJaeger> dianefleming, text was great - but not as part of the backport
13:23:23 <dianefleming> yeah, I didn't notice it was a backport until i was in too deep - sorry about that
13:23:44 <AJaeger> dianefleming, easy to solve, still we have to be carefull
13:23:50 <annegentle> dianefleming: heh :)
13:23:56 <annegentle> dianefleming: no worries
13:24:19 <AJaeger> Do we need the usual 2 approvals for simple backports?
13:24:25 <dianefleming> i wish there was a way to auto-backport - seems like we do too much work on those
13:24:35 <AJaeger> Or do we want to do them quicker?
13:24:49 <dguitarbite> cherry picks +1 easier to avoid accidents
13:24:55 <annegentle> AJaeger: no, I think we should make it a policy that if the backport merged into master, only one core needs to review it for backport
13:25:00 <chandankumar> dianefleming, actually how backporting is done, so that i cna help.
13:25:06 <chandankumar> *can
13:25:15 <annegentle> AJaeger: we're a little different from other projects in that we don't have a stable team
13:25:19 <annegentle> dedicated stable team
13:25:32 <annegentle> so I think core is our dedicated stable team and we can make fast merges
13:25:42 <AJaeger> chandankumar, see the link above by annegentle
13:26:03 <AJaeger> So, if I propose a backport, somebody else give the +2/approval?
13:26:18 <annegentle> There is a blueprint for automating backports: https://blueprints.launchpad.net/openstack-manuals/+spec/attempt-backport-by-commit-message
13:26:29 <annegentle> AJaeger: yes that seems safe and sane to me, anyone else think that's crazy?
13:26:53 <dianefleming> sounds good to me - the +2 approval on backports
13:26:59 <dguitarbite> annegentle: safer and easier for newbies/non-git-gerrit geeks
13:27:10 <annegentle> I think backports fade out over time, but yeah, we do a LOT of them especially on install guide
13:27:20 <NickChase> I'm all for the automated backport
13:27:38 <AJaeger> It'S only install guide and config reference - and Install Guide needs a bit more testing and fixing
13:27:38 <annegentle> NickChase: I'm just not convinced it can ever be automated, those have rebase conflicts all the time
13:27:44 <annegentle> AJaeger: yeah true that
13:28:19 <AJaeger> right now I'm checking that patches get proposed for the guides and propose some myself to avoid conflicts
13:28:28 <NickChase> annegentle:  I'm not a git expert, but seems to me that if it works it'd be helpful, but for those cases where it doesn't we haven't lost anything.
13:28:40 <annegentle> NickChase: yeah true
13:28:56 <annegentle> Ok still no sarob but we can start talking about rst to xml so nermina has an idea of where they are
13:29:01 <NickChase> plus there are people (like myself, admittedly) who just don't know how to do it, but we CAN mark whether it should be done
13:29:13 <annegentle> NickChase: yep, and that helps too
13:29:18 <dianefleming> automation would save a lot of time - even if we have to manually merge
13:29:28 <annegentle> #topic devref rst to xml conversion
13:29:34 <NickChase> and it forces people to think about whether a patch should be backported; I suspect there are  lots of changes that should have gone back to grizzly but didn't because people just didn't htink of it
13:29:45 <annegentle> NickChase: you know, that's true too
13:29:58 <annegentle> dianefleming: yeah automating some steps helps
13:30:07 <annegentle> is that even grammatically correct? Anywho
13:30:13 <annegentle> We can talk more about automation!
13:30:25 <AJaeger> NickChase, That's why we demand the "backport: havana" or "backport: none" now for all changes that target guides that we do separately for havana
13:30:25 <annegentle> So we had several concerns with their original patch
13:30:31 <annegentle> oh maybe I should back up even further
13:30:36 <AJaeger> At least it's now a concise decision and not neglect
13:30:46 <annegentle> The goal for the training manuals is to reuse all they can to reorganize the content into training guides
13:30:50 <dguitarbite> are you guys working on rst to xml? I believe that sarob is working on it as of now
13:31:01 <nermina> was that the original patch you sent me, annegentle
13:31:08 <nermina> ?
13:31:25 <AJaeger> annegentle, I agree with your proposal moving forward.
13:31:41 <chandankumar> annegentle, we can do rst to xml conversion by using rst2xml package provided by docutils.
13:31:44 <annegentle> nermina: the patch I sent was their attempt at automation manually, bringing in content they felt was missing
13:31:45 <AJaeger> The question to me is whether we should ask the projects like nova to remove patches and point to the documentation that we write?
13:31:50 <annegentle> chandankumar: yes that's their patch
13:31:54 <annegentle> #link http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/training-guide
13:32:06 <nermina> that's what i thought, annegentle
13:32:16 <annegentle> The training manuals have four personas in mind: associate, operator, developer, architect
13:32:46 <nermina> ok
13:32:59 <annegentle> #link https://review.openstack.org/#/c/50509/
13:32:59 <shaunm> annegentle: are there write-ups of those personas yet?
13:33:15 <dguitarbite> sarob is working on it, here is the link for it : https://github.com/sarob/openstack-sarob
13:33:50 <nermina> annegentle, is the audience documented somewhere?
13:33:53 <annegentle> shaunm: I'm looking
13:34:18 <dguitarbite> audience in d sense for the associate, operator .. ??
13:34:27 <annegentle> Ok, so if you look at "what does this book intend to teach" like http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/training-guide/bk004-ch001-architect-what-does-this-book-intend-to-teach.xml
13:34:35 <annegentle> you see the idea behind their guide
13:35:03 <annegentle> also
13:35:05 <annegentle> #link https://blueprints.launchpad.net/openstack-manuals/+spec/training-manuals
13:35:14 <dguitarbite> heras of now its there on the wiki https://wiki.openstack.org/wiki/Training-manuals
13:35:19 <annegentle> #link https://wiki.openstack.org/wiki/Training-manuals
13:35:37 <dguitarbite> its a tricky thing to get it sorted
13:35:42 <annegentle> The idea from our perspective (docs) is that we'd offer them guidance, avoidance of pitfalls, a process and tools
13:35:57 <annegentle> Sort of like incubation within the Docs program, until they can have their own program
13:35:58 <dguitarbite> we are working on the official version for the intended audience
13:36:32 <annegentle> dguitarbite: my understanding is that Associates is the first course
13:36:33 <nermina> thanks, dguitarbite
13:36:42 <dguitarbite> nps
13:36:43 <annegentle> dguitarbite: and not devs yet
13:36:59 <dguitarbite> yes
13:37:03 <annegentle> nermina: but apparently they discovered missing info and wanted to bring it in from dev guides
13:37:16 <nermina> right
13:37:19 <dguitarbite> annegntle: associate is the first one, we plan to get the alpha version out before end of this year
13:37:19 <annegentle> so my suggestion is that the info that's missing should find a place in openstack-manuals
13:37:38 <annegentle> nermina: I think it's great if you can help them, because it'll make the docs better
13:37:52 <nermina> annegentle, could i get a week to analyze this and come up with some recommendations?
13:38:02 <annegentle> AJaeger: I'm glad you can double-check my sanity, thanks
13:38:18 <annegentle> nermina: absolutely fine by me, and if dguitarbite knows their timeline, then it sounds like a week is good
13:38:19 <AJaeger> can we somehow sync on a common set of persons between training and doc?
13:38:30 <nermina> annegentle, i'll match it up against the guides
13:38:31 <annegentle> AJaeger: htinking
13:38:52 <annegentle> AJaeger: so, the user committee has personas, to me those match more with docs
13:38:55 <nermina> and see how they can be interlinked, annegentle
13:39:02 <annegentle> AJaeger: training is more about "what job can I get after completing this"
13:39:12 <annegentle> nermina: yes... pondering
13:39:24 <AJaeger> I see
13:39:29 <nermina> we could do a blueprint, annegentle
13:39:39 <annegentle> I'm not sure I'd make a 1:1 match, honestly, because of the "jobs jobs" focus of training
13:39:55 <dguitarbite> AJaeger: Training will also have quizes, PPT generators etc. etc. which you would not prefer to keep in the manuals
13:40:04 <nermina> no, i meant to see how they can relate, annegentle
13:40:17 <nermina> synchronize, if you will
13:40:29 <AJaeger> dguitarbite, I agree - but the more we align our goals, the easier we can share.
13:40:38 <annegentle> nermina: well, I made Sean do a blueprint for automation, and his training manuals, so I don't know if another blueprint is necessary, but it would certainly help if you can study their blueprint
13:40:57 <annegentle> nermina: and perhaps update their blueprint
13:41:17 <annegentle> nermina: for exapmle, their Book structure section
13:41:24 <nermina> annegentle, no problem, that sounds good
13:41:32 <annegentle> nermina: ok, excellent
13:41:59 <dguitarbite> AJaeger: I have proposed this to sean for reusing the training manuals, thats the reason we spent time on xpath ... the basic goal is to reuse as much openstack-manuals as possible
13:42:08 <annegentle> AJaeger: yeah I agree with goal alignment to a point, but if the goal is to let them eventually run their own program, do we all align with the user committee personas as an overarching organizer?
13:42:36 <annegentle> AJaeger: and that might just be an academic question more than pragmatic, not sure yet
13:42:54 <nermina> annegentle, ajaeger, i think their set is more specific and defined within practices
13:42:59 <AJaeger> annegentle, as far as it makes sense. If we can agree on three out of four it would be better than on none. Might indeed be academic...
13:43:12 <AJaeger> nermina, in that case let's move on and ignore me ;)
13:43:16 <annegentle> Hee
13:43:34 <annegentle> It's ideal to collaborate and understand each other as much as possible!
13:43:44 <nermina> i agree annegentle
13:43:51 <nermina> i see your point too ajaeger
13:44:12 <annegentle> dguitarbite: I really don't want to slow your progress, and I do think all the docs will be better after this analysis
13:44:18 <nermina> i feel like the training team is closer to the user community
13:44:28 <nermina> and they know their needs
13:44:35 <annegentle> nermina: yes, I think so too, they are doing working sessions at user groups, which is really cool
13:45:03 <dguitarbite> annegentle: agree
13:45:30 <annegentle> Ok, I think that's it for topics, how about open discussion
13:45:35 <annegentle> #Open discussion
13:45:54 <annegentle> I finally got the sitemap.xml ready, thanks to dwcramer for the help with the XSLT
13:46:05 <NickChase> Did you want to talk about the licensing thing?
13:46:07 <annegentle> This is the first release I couldn't do it all manually
13:46:09 <annegentle> NickChase: yes!
13:46:12 <nermina> happy birthday, annegentle!
13:46:16 <annegentle> nermina: thanks!
13:46:32 <NickChase> annegentle: cool on the sitemap.xml
13:46:41 <dianefleming> @annegentle - two topics - 1) automation of command ref and 2) removal of API references and introduction of API guide
13:46:51 <annegentle> dianefleming: sure
13:46:57 <NickChase> so regarding the licensing, we have the doc from the lawyer
13:47:09 <annegentle> Ok NickChase first
13:47:31 <NickChase> (sorry, didn't mean to jump in and be rude!)
13:47:39 <dianefleming> I wrote a blueprint on 2) but I need to write a blueprint on 1) - my main question is, who needs to review/approve the blueprints?
13:48:00 <NickChase> the trouble is that the license for the docs is specified in the CLA
13:48:23 <NickChase> so if we are going to change the license, we need a way for people to acknowledge that change.  basically...
13:48:36 <NickChase> we have to get their agreement that changes they submit are now under this new license.
13:48:51 <NickChase> For a small team, that's not a big deal; we could conceivably do it manually
13:49:00 <NickChase> but if we change the CLA, that's a big, big deal.
13:49:30 <NickChase> Also, we need to define "attribution" and what we want people to do with our books if they reuse them (ie, keep attribution, remove it, etc.)
13:50:05 <NickChase> So those are the basic issues.  Do we need to actually DO anything or are we going to let the board just make some decisions and THEN talk about it?
13:51:19 <annegentle> NickChase: we're going to let the board churn on it :)
13:51:40 <annegentle> NickChase: that's a great report, thanks for the leg work!
13:51:41 <NickChase> annegentle: sounds like a plan. :)
13:51:44 <NickChase> my pleasure
13:51:50 <annegentle> Ok, dianefleming you're up
13:51:54 <dianefleming> ok!
13:52:21 <dianefleming> for the command ref automation (actually command ref content in the user guides), i need to write a blueprint - who needs to review/approve it?
13:52:42 <annegentle> dianefleming: I found this: https://pypi.python.org/pypi/sphinxcontrib-programoutput
13:52:46 <dianefleming> for the api refs removal and addition of the api guide, can I assume that's approved or do I need to pass that by dev?
13:53:09 <annegentle> dianefleming: it's implementation detail, but found it does mean a change to requirements.txt, which would have to go through ci core approval I believe
13:53:33 <annegentle> dianefleming: so, for automation of command ref output, it might be a blueprint within ci? I dont' mind it being in openstack-manuals though
13:53:41 <dianefleming> ok
13:53:49 <sarob> Sarob here
13:53:51 <dianefleming> i can put command ref blueprint in ci
13:53:54 <annegentle> hey sarob!
13:53:55 <dianefleming> hi sarob
13:54:01 <NickChase> hi sarob
13:54:01 <sarob> Sorry late
13:54:19 <sarob> Just hit sfo
13:54:27 <annegentle> dianefleming: I can give you more details after the meeting about requirements.txt
13:54:32 <annegentle> welcome sarob
13:54:37 <sarob> Thx
13:54:40 <dianefleming> thanks - i'll be in the office around 11am
13:54:48 <nermina> hi sarob
13:54:51 <annegentle> sarob: you'll see the discussion in the notes, but the gist of it is nermina is going to take this week to analyze the content
13:54:54 <dguitarbite> hi saob
13:55:02 <dguitarbite> *sarob
13:55:05 <dianefleming> as for api ref/api guide, it means removing the repos for the api refs, which would impact dev - right?
13:55:05 <annegentle> dianefleming: cool
13:55:16 <dianefleming> so they should approve/reject that blueprint?
13:55:19 <annegentle> dianefleming: yeah that part is really tough to say how the individual projects would react
13:55:32 <annegentle> dianefleming: it's nearly a TC level question, since it affects all projects
13:55:42 <annegentle> dianefleming: I'm averse to removing them, honestly
13:55:42 <dianefleming> okay, i'll talk to you about that when I come into office
13:55:45 <annegentle> dianefleming: ok
13:55:54 <dianefleming> hmmm - let's talk
13:56:06 <sarob> I late but
13:56:20 <annegentle> dianefleming: not sure if it's just because I created them due to some conflict coming out among core members of nova
13:56:36 <sarob> Can we move the devref project rst as well then?
13:56:51 <sarob> Or discuss with TC at the same time?
13:57:34 <sarob> Cause doing one page move at a time is going to kill our project
13:58:20 <annegentle> sarob: pretty sure we're not trying to kill your project :)
13:58:41 <sarob> Nope I don't think that
13:58:42 <annegentle> sarob: it's not one page at a time, it's looking at your larger outline and ensuring the pieces fit
13:58:58 <annegentle> sarob: is this all content needed for associates?
13:59:19 <annegentle> sarob: we also talked about persona alignment
13:59:24 <sarob> Many pages yeas
14:00:07 <annegentle> sarob: I think nermina will have a good handle on 4-5 patches (just guessing) that will need to come in
14:00:22 <sarob> It is more straightforward to mass convert while still developing the documentation
14:00:27 <sarob> And flow
14:00:55 <nermina> sarob, i'll see how the content is organized and how it can communicate with the user guides
14:01:21 <annegentle> sarob: I think you'll get conversion but probably not as big as https://review.openstack.org/#/c/50509/ ended up
14:01:40 <annegentle> sarob: and I do think some of it is developer, not associate
14:01:50 <sarob> True
14:01:57 <annegentle> sarob: do you you have a timeline?
14:02:04 <sarob> It will land in the same place
14:02:37 <annegentle> sarob: dguitarbite was saying by Dec.
14:02:46 <sarob> Yes
14:02:48 <annegentle> wow it's after 9
14:02:58 <annegentle> Ok, I'm going to end this meeting, but please continue in #openstack-doc
14:03:01 <annegentle> #endmeeting