14:00:36 #startmeeting docteam 14:00:37 Meeting started Wed Mar 25 14:00:36 2015 UTC and is due to finish in 60 minutes. The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:00:38 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 14:00:40 The meeting name has been set to 'docteam' 14:00:45 Okay. Here's our agenda 14:00:49 Good afternoon! 14:01:01 hi! glad you can make this time! 14:01:07 #link https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting 14:01:23 let's start with action items from last time 14:01:36 (none) 14:01:39 I like hat 14:01:41 that even 14:02:01 I dont' think there's anything from apac either but let me look real quick 14:02:33 nope 14:02:35 hi 14:02:43 hey 14:02:54 Okay that's it for action items from meetings 14:02:57 #topic Four final theme bugs 14:03:13 So I think there are four things we have to fix before releasing 14:03:21 Search working, bug link working, TOC links working, scoped/conditional build working 14:03:36 yesterday AJaeger got the scope build working, thank you AJaeger! 14:03:39 and whew! 14:03:44 woohoo 14:03:48 The search has a patch in place, let me find the link 14:03:54 I see the following problems with user guide/admin user guide: Title of admin user guide is wrong. We have no glossary. 14:04:11 but those are not related to theme 14:04:25 AJaeger: okay, good to know. I didn't have working glossary as a "must have" in this phase. 14:04:35 good to know 14:04:42 Search fix: 14:04:44 #link https://review.openstack.org/#/c/167028/ 14:05:06 Bug link in progress: 14:05:08 #link https://review.openstack.org/#/c/160151/ 14:05:26 Oh I almost forgot, we need next and prev links as well 14:05:28 so still four things 14:05:33 Next/Prev: 14:05:35 #link https://review.openstack.org/#/c/163656/ 14:05:52 TOC links: 14:05:54 #link https://review.openstack.org/#/c/160354/ 14:06:15 all of those need to be landed this week or next for us to publish RST by April 9th. 14:06:22 does anyone have any other showstoppers? 14:06:34 meaning, without this, we shouldn't publish from RST 14:06:49 I don't believe the licensing is a showstopper, nor the glossary. 14:06:50 make the goes 14:06:58 agreed 14:07:02 I think we can iterate 14:07:25 AJaeger: what's the typical turnaround for global requirements? If I get these four into a new release, can we push for global to get updated? 14:07:45 annegentle, we can releease without global requirements. 14:08:07 The build process always takes the latest release, requirements is only important for local setup... 14:08:12 AJaeger: ah! 14:08:19 AJaeger: no kidding. hm. 14:08:27 AJaeger: I thought it would be pinned to a version number 14:08:30 and global requirement is something I have to do some more discussion on how to do it properly 14:08:41 annegentle, we have > version so that works 14:08:47 AJaeger: okay, sounds like you have a handle on it then 14:08:54 wow idiomatic phrase there :) sorry. 14:09:05 annegentle, AJaeger hello 14:09:12 morning / evening dhritishikhar_! 14:09:44 ok, how should I update the community this week on our RST progress? ML post? Should I do another blog post? 14:09:50 I think ML post should be sufficient 14:10:20 Another topic that we'll have to discuss, and I think I'll start on the list, is what criteria do we use for choosing what goes to RST next? That'll certainly be a good summit topic. 14:10:57 so be thinking of ideas for criteria (not justifications for your favorite, ha) 14:11:09 any questions on RST, theme, migration? 14:11:18 we should stop patching the current user guides 14:11:21 We haven't really had to "freeze" the content, but I'll take a look today. 14:11:26 AJaeger: heh it's like you're a mind reader 14:11:37 to not have newer content in the xml that is newer than RST 14:11:38 ;) 14:11:49 AJaeger: yeah the freeze has been unintentional so far, as in, no one has updated the user guides anyway 14:12:03 AJaeger: Ok I'll add that to my ml post 14:12:03 annegentle, there are one or two patches in the queue AFAIR 14:12:17 AJaeger: ah, good to know, that's what I was going to check 14:12:22 annegentle, add title for admin guide to the todo list 14:12:23 we should discuss the networking guide being published to /networking-guide as docbook still 14:12:30 i thought that should be rst 14:12:48 AJaeger: do you happen to know, does https://wiki.openstack.org/wiki/Documentation/Migrate have all files listed? 14:12:53 Sam-I-Am, it'S not published actively - that'S frozen content. Let's ask annegentle to remove it 14:13:00 Sam-I-Am: yep I want criteria for completion before publishing anything else to RST 14:13:03 annegentle, no idea ;( 14:13:14 annegentle: ok. the networking guide is going to be... interesting. 14:13:15 Sam-I-Am: and yes, should the XML be deleted? 14:13:25 annegentle: yes, it should be deleted 14:14:04 Sam-I-Am: as long as we know how to get the old XML from a change id or commit id or whatever the git term is for that then I'll propose a deletion 14:14:14 (I know how, does everyone else) 14:14:34 annegentle: what do you mean get it? 14:14:54 Sam-I-Am: you can retrieve it locally with a git command even after it's removed from master branch 14:15:01 it being XML files 14:15:06 ah 14:15:07 so, them, heh. 14:15:13 just don't want to cause freakouts 14:15:22 we can discuss outside of the meeting 14:15:27 #action annegentle to delete XML content from networking guide master branch 14:15:33 #undo 14:15:35 Removing item from minutes: 14:15:36 okay 14:15:47 Moving on in... 14:16:04 meh, I hate countdowns :) 14:16:07 #topic Licensing updates 14:16:09 5... 14:16:32 So I meant to send a more detailed context-setting email about licensing, but ended up sending what I sent last night, ha. 14:16:46 its pretty good to clear this all up 14:16:50 its been really confusing 14:16:59 Basically, I audited the 14 guides I consider governed by the common docs team 14:17:21 #link https://wiki.openstack.org/wiki/Documentation/ContentSpecs#Licenses 14:17:31 I think I still need legal guidance on the desired outcome 14:17:44 thanks a lot for doing this, annegentle ! 14:17:47 so hopefully I can get that on the legal ML, but I also have Stefano (reed) who can help from the Foundation. 14:18:28 I do want to bring up here that we all should be contemplative about putting content outside of gerrit 14:18:58 why? 14:19:00 I also wanted to be sure those of us on the team get what we want -- I think that less confusion will be great. 14:19:14 Sam-I-Am: so that we don't end up having to do an audit trail with a team of lawyers some day 14:20:26 I think it's best if the output displays the license. Sounds like everyone agrees on that? 14:20:33 annegentle, I'd like to have a clear and simple rule ;) 14:20:47 output displaying the license would be nice 14:20:52 Do we think we should indicate to any docs contributor what happens to the content license? It's a ton of education. 14:20:53 annegentle: thats what people see 14:22:10 I'm a fan of a 'submissions are under copyright' line to the new contributor message 14:22:20 I'm not even clear myself today what it means to sign the CLA from a content/writing standpoint 14:22:34 annegentle: its kind of weird that writing is not "code" per se 14:22:35 yeah - but that's a larger problem 14:22:39 even though it is... compiled. 14:22:49 and may contain codey things 14:23:01 sicarie: that's good input, and we could add that fairly easily 14:23:58 Sam-I-Am: there's no legal distinction today 14:24:10 well I shouldn't say that, I barely know myself 14:24:57 it confuses me a lot... particularly apache vs. cc 14:25:25 basically, the goals are: open as possible so that it gets as wide distribution and reuse as possible while following brand guidelines 14:25:38 with those goals, do we want the outcomes: 14:25:43 - every reader knows the license 14:25:52 - people know if and how to reuse the docs 14:26:03 - contributors know what happens to their upstream contributions 14:26:19 that third one's the hardest to measure 14:26:27 for that matter, so's the first one 14:26:55 they are not written for plebes 14:26:56 Sam-I-Am: does it concern you really though? 14:27:24 I think most people contribute to open source with an understanding that sharing is desired 14:27:29 not really. 14:27:33 so I'm not too worried. Yeah. 14:27:45 the only thing i dont particularly care for is people lifting stuff verbatim and posting it elsewhere without reference to the original 14:28:07 Sam-I-Am: even CC-by doesn't desire to prevent that 14:28:19 Sam-I-Am: if you wanted to avoid that you'd want CC-by-sa 14:28:23 er 14:28:27 I mean the one with attribution 14:28:36 but anyway, the Foundation doesn't want that 14:28:58 ok on to 14:29:01 ok 14:29:02 #topic Specialty teams 14:29:10 Anyone from HA Guide want to report? 14:29:15 I need to catch up after my week off anyway 14:29:46 plus all my emails are digest form, sigh 14:30:04 so... 14:30:14 HA guide... think we're still banging out the topics 14:30:18 and their order, specifically 14:30:27 #link https://wiki.openstack.org/wiki/Documentation/HA_Guide_Update 14:30:30 the meeting time got screwed up with the time change 14:30:36 Okay, I'm reading Matt's update now 14:30:43 Oh yeah. crazy time change 14:31:07 its moving slowly 14:31:17 there is a blueprint, 14:31:19 #link https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ha-guide 14:31:39 It's approved from Feb 2014, but it would be great to get a spec 14:31:53 i think specs get forgotten 14:32:04 the owner of the sub-team should probably managed it 14:32:05 -d 14:32:09 the contributors dont have the time 14:32:23 I do worry this (ha) is getting bigger... possibly out of scope. 14:32:29 I'll try to circle back with Matt 14:32:30 what do you mean? 14:33:01 Sam-I-Am: with all the rest of the guides needing work too, should we prioritize ha work? 14:33:28 Sam-I-Am: it's near impossible to get the project teams to do the writing. so it's tough to find specialists. 14:33:33 i think they're all pretty desperate for contributions - ha, install, networking, etc 14:33:44 Sam-I-Am: so it's worrisome and descoping is one way to conserve resources. 14:33:53 I look at our numbers and worry. 14:34:13 but, the discussion veers into "well then why have a big tent" 14:34:25 which numbers? 14:34:43 if we drop 6 core docs reviewers our numbers of people who can +2 are quite low 14:34:55 add more cores? 14:35:11 was there some sort of plan to make sub-team owners core? 14:35:17 Sam-I-Am: still, even if we get back to 20 cores, how do we know how many are enough? 14:35:18 or does that only apply to separate repos 14:35:26 Sam-I-Am: it's most easily applied on repos 14:35:43 yesterday's TC meeting had a discussion about "maintainers" which is similar to our specialty teams 14:36:02 so a lot of the teams are having similar discussions about resources and ensuring recognition and allocation wisely 14:36:31 hopefully moving to rst we can reduce the barrier to entry and/or automate more stuff 14:36:34 believe me, I don't want to get rid of specialty teams or guides 14:36:39 as long as rst doesnt become to encumbered 14:36:47 Okay anyone from training? 14:37:17 Good to see them adding people. 14:37:25 Go ahead with Install Guide then. 14:37:29 hello 14:37:53 right now we’re in “update all the things” mode for Kilo, that being the top priority 14:37:55 hi KLevenstein! 14:38:10 nice to see Bernd stepping up there! 14:38:11 i have a big keystone patch coming :) 14:38:18 it changes All The Things 14:38:43 heh saw that 14:39:02 that patch is the biggest news, currently. apart from the fact that, well, the team exists. :) 14:39:06 using a lot of the rpc work to determine changes for kilo 14:39:13 KLevenstein: so for process, does the spec have to be approved prior to work merging? 14:39:18 our team doesnt have a lot of veterans yet 14:39:51 re: the spec, I’m open to ideas on process, but I feel like the spec addresses wider material than just “get it done for Kilo” 14:39:58 and I don’t want it to stand in the way of work 14:40:06 or does the review become the place to discuss? Ideally the spec review is finalized before the patches come in, but with the time crunch, I understand a need for speed. 14:40:11 that said, it has a lot of info that I want us to keep on our collective radar 14:40:24 next time we'll get on this earlier (now that trunk isnt published) 14:40:26 I worry that Sam-I-Am will do work that devs overturn. 14:40:53 I've seen too many last-minute reversals. but maybe it's fine 14:41:11 what do you mean? 14:41:47 like the keystone team deciding to deprecate v2 but no one letting them, that sort of thing. 14:42:09 I mean, the spec seems to offer the right balance to me. 14:42:20 heh, yeah. there's a lot of fun around that, but i think i found the right balance in my patch 14:42:20 of "get it done in a timely way in a scope that's doable" 14:42:24 and 2 days worth of testing 14:42:30 Sam-I-Am: okay 14:42:32 personally I’m amenable to whatever makes the most sense right now and doesn’t get in the way of getting the Kilo stuff done 14:42:52 KLevenstein: maybe it's better to publish the spec this week, just to have process in the right order, and the plan communicated, so that reviewers know what to look for. 14:42:57 fair enough 14:43:01 KLevenstein: then amend the spec if required. 14:43:08 annegentle: another thing... 14:43:08 regarding keystone, we should follow up on berendt's email and discuss keystone in the cli guide: http://lists.openstack.org/pipermail/openstack-docs/2015-March/006073.html 14:43:11 Sam-I-Am: you good with that? 14:43:20 yeah 14:43:38 so, in light of not frying myself, i'm only testing/updating the ubuntu content 14:43:41 AJaeger: oh yeah, I need to write back, add a deprecation note. there's too many installs already to just remove 14:43:46 Sam-I-Am: ok 14:43:51 most of the service config should work fine on other distros 14:44:02 however, for keystone, redhat/suse use different apache configs 14:44:31 so, what i'd like is to merge patches that work for 1 distro, and then address other distros in additional patches rather than waiting until all distros work after a bunch of -1s 14:44:41 I endorse this plan 14:44:50 Sam-I-Am, fine for me 14:44:51 Sam-I-Am: I'm okay with that also, esp. since it's not published. 14:44:55 in other words... if i finish ubuntu and its tested by kilo release, we publish it. if rhel isnt done, we dont publish it. 14:44:57 Sam-I-Am: does the spec note that? 14:45:04 pretty sure we can publish per-distro 14:45:07 Just want to be sure it's communicated 14:45:10 yeah, i think it says "we 14:45:15 we're not publishing untested stuff 14:45:29 Sam-I-Am, add this information to the spec - that a patch fixing one distro is fine in the initial phase. 14:45:32 however it doesnt mention my patching idea 14:45:37 ok aj, i can do that 14:45:51 okay 14:45:57 that'll help reviewers 14:46:04 otherwise we don't know what's intended 14:46:23 i'm going to note it in my commit message for this patch 14:46:31 cool 14:46:32 but the spec makes more sense long term 14:46:36 ok 14:46:38 this is one hell of a commit message 14:46:40 kind of its own doc 14:47:10 heh that's what's helpful 14:47:16 but it means the install guide wanders more toward a production system 14:47:20 Ok, anyone here for user guides? 14:47:32 that's good, closer to production 14:47:49 you can thank dolph :) 14:48:01 I do think that the user guide team can help with the "do we need to replicate/duplicate topics in each guide?" 14:48:15 I think as we get further from "book" looking deliverables it'll be natural 14:48:23 but it's nice to know we have conditional for topic-level. 14:48:36 Not planning on conditionals at a phrase level. 14:48:42 does that make sense at all? 14:48:54 i'm still thinking eventually this will all be in one place... admin/operator/user 14:49:15 less confusion on where to find stuff 14:49:16 it would make life a lot easier if it's all one book ;) 14:49:23 (from the tooling side ;) 14:49:28 i see a lot of issues where people just dont know where to look for stuff 14:49:42 I also wanted to note here that Bryan Payne is handing the Security Guide reins to Nathaniel Dillon 14:49:49 i was sort of surprised in the install guide that we're linking to the ops guide for some things instead of the admin or user guides 14:49:54 I should probably look for wiki pages to update. 14:50:12 Sam-I-Am: I just told someone in a review to point to the user guide instead of the ops guide for floating IPs. 14:50:17 Sam-I-Am: so that's fixable 14:50:54 true. i'm still in the one-guide camp heh. 14:51:11 I don't have much to report for API docs other than Diane has been going great gangbusters on bug fixes. 14:51:13 yay! 14:51:32 Anything else from specialty groups? 14:51:36 Nick is off this week 14:51:36 networking? 14:51:36 annegentle, hug her from me - she does a great job there! 14:51:41 AJaeger: :) 14:51:44 yeah, he's sort of off 14:51:55 Sam-I-Am: oh yeah Networking, didn't have it on the agenda, will add 14:51:59 he submitted a patch that i threatened to -1 because he wasnt vacationing hard enough 14:52:21 anyway, we're moving along slowly. 14:52:35 I hope I set an okay example for stepping away from computer. 14:52:44 annegentle, sort of ;) 14:52:46 :) 14:52:48 annegentle: you didnt vacation hard enough either 14:52:59 So sounds like XML can be deleted 14:53:08 and the scenario template is now in good shape 14:53:31 and current networking published version can be deleted 14:53:34 anyway, right now i'm having trouble splitting time between the install and networking guide content. we almost have all the scenarios done, at least ready for conversion to RST... after which point we can address minor technical issues (and there are some). 14:53:48 elke sort of ended up in the hospital again, so things are backed up 14:54:12 annegentle, http://docs.openstack.org/networking-guide/content/ch_preface.html 14:54:13 oh no! 14:54:16 I hope she's okay 14:54:24 one thing we need to discuss in light of kilo coming soon (and a presentation at the summit) is... when and what can we publish? 14:54:40 i dont know what she had done, but it sounded semi-planned 14:54:42 AJaeger: so that's there now, okay. 14:54:52 annegentle, that should be deleted 14:54:59 AJaeger: ok, got it 14:55:05 Sam-I-Am, once you have enough content we can publish quickly ;) 14:55:07 seems to me that the meat everyone wants is the scenarios. aka... how do i configure X? 14:55:15 #action annegentle to FTP delete the XML published networking guide 14:55:33 Sam-I-Am: AJaeger: so is one scenario enough to publish? 14:55:44 annegentle: i think we should have all of them 14:55:46 that is, one page? 14:55:54 Sam-I-Am: is that realistic by May 18? 14:56:09 as long as we get someone to convert to rst... most of the writing is done. 14:56:19 have a look at the content: http://docs-draft.openstack.org/21/165121/11/check/gate-openstack-manuals-tox-doc-publish-checkbuild/f00f84a//publish-docs/networking-guide/content/index.html 14:56:19 there's one scenario that isnt written yet, but its not hard. 14:56:22 Sam-I-Am: are there xml-based scenarios? 14:56:27 That's too little IMHO 14:56:37 no. they're RST... or they're markdown in my repo. 14:56:49 too much TBD 14:56:51 we only have one converted to rst because elke 14:57:01 and first we need the 4 theming bugs fixed and a new theme released 14:57:03 there's a second one that sean uploaded, but it needs work. 14:57:15 AJaeger: they could publish with oslosphinx if needed 14:57:22 AJaeger: I know that's not ideal. 14:57:30 its in my queue to look at, but not sure when that'll happen 14:57:45 What about publishing only what doesn't have TBD? 14:57:46 content takes priority over rst munging for me 14:57:57 Is the rst conversion for specialty docs as well, and if so is there a planned migration completion date? 14:58:01 Sam-I-Am: is markdown that much easier than rst? 14:58:13 annegentle: no, but github renders it better. 14:58:16 sicarie: User Guide and Admin User Guide are the only two planned for this release 14:58:23 sicarie: hence the discussion 14:58:29 annegentle: they're about the same. also, my browser has a markdown plugin :) 14:58:37 sicarie: and a need to set criteria for what gets migrated next. 14:58:43 annegentle: thanks, just wondering if I need to start planning for that as well :) 14:58:52 sicarie: definitely help figure out criteria :) 14:59:11 next up - asciidoc :) 14:59:50 Sam-I-Am: so your need is something on docs.openstack by summit? 15:00:01 Sam-I-Am: or is that really the outcome? 15:00:05 annegentle: yes, because session 15:00:11 "we did X... but you cant see it" 15:00:16 Sam-I-Am: I saw it was accepted 15:00:17 not going over well 15:00:32 the scenarios are the primary example of collaboration 15:00:36 Sam-I-Am: so, I'm fine with publishing it as long as the TBDs are not there 15:00:37 we're over the hour, annegentle time is up 15:00:39 and they're going to be done 15:00:41 ah yes 15:00:42 sorry 15:00:53 let's continue in #openstack-doc for open discussion 15:00:56 #endmeeting