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