14:00:36 #startmeeting docteam 14:00:36 Meeting started Wed Aug 6 14:00:36 2014 UTC and is due to finish in 60 minutes. The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:00:37 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 14:00:39 The meeting name has been set to 'docteam' 14:00:41 hello 14:00:46 hi berendt! 14:00:46 Hey, all 14:00:53 hey NickChase 14:01:06 Agenda is here: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting 14:01:15 #topic Action items from the last meeting 14:01:38 regXboi to add list of existing neutron doc bugs to the blueprint wiki page 14:01:58 I'm looking 14:02:20 #link https://wiki.openstack.org/wiki/NetworkingGuide/TOC 14:02:24 Not yet 14:02:35 he did add some sections to the TOC 14:03:04 I wonder if he thought that was what he was supposed to do 14:03:11 ah maybe so 14:03:13 yo 14:03:20 hey, sam-i-am 14:03:36 There's also this for tracking 14:03:38 #link https://etherpad.openstack.org/p/neutron-docs-juno 14:04:14 that actually leads nicely into the next topic 14:04:16 #topic Blueprint plans in progress 14:05:09 We have two docs-specs done https://review.openstack.org/#/q/project:openstack/docs-specs,n,z 14:05:15 Glossary sharing is done, thank you AJaeger 14:05:34 Needs approval from infra team but otherwise done (I hope ;) 14:05:36 the heat-templates spec is done, thank you Gauvain (who's on vacay) 14:05:41 AJaeger: ah yes that's right 14:05:51 then there are two others I want specs for 14:05:59 which are? ;) 14:06:02 one is my responsibility, and I'm working with fifieldt, on redesign 14:06:10 sld: can't type any faster :) 14:06:12 to see all specs, go to specs.openstack.org 14:06:13 lol 14:06:27 It's related to an older blueprint 14:06:34 #link https://blueprints.launchpad.net/openstack-ci/+spec/ci-doc-automation 14:06:39 look at that 2011 date :) 14:07:04 specifically, this part: 14:07:05 Use git review to edit docs on web: https://bugs.launchpad.net/openstack-ci/+bug/1003153 - Offer a way for readers to edit a page in a lightweight web-based editor, then use git-review in the background to submit a review to Gerrit. 14:07:07 Launchpad bug 1003153 in openstack-ci "Edit a doc page in a lightweight web-based editor" [Wishlist,Triaged] 14:07:28 Awesome idea! 14:07:29 I will have a spec, I promise :) 14:07:47 and it may or may not require redesign 14:07:55 annegentle, add yourself an #actionitem ;) 14:08:06 lol ajaeger 14:08:09 but it'd be great to get a page-based method out there 14:08:10 :) 14:08:54 #action annegentle to write spec for docs site redesign/experience design 14:08:57 #link https://blueprints.launchpad.net/openstack-manuals/+spec/redesign-docs-site 14:09:34 Then there's the Networking work, I really want a spec for that since there's a lot of activity and coordination needed 14:09:51 Sam-I-Am: I think we'll have Shaun do it since you and Phil are busy 14:09:56 it being the spec 14:09:59 sure 14:10:13 and that's it for blueprints we're targeting that need specs 14:10:20 just need to move the toc wiki to it 14:10:33 put that toc wiki link here for reference? 14:10:37 #link https://blueprints.launchpad.net/openstack-manuals/+spec/add-ceilometer-admin-guide-to-openstack-manuals 14:10:56 this one is fine without a spec, the ceilometer guide (though with all the mailing list discussion I wonder if a spec would've helped?) 14:11:00 sld: https://wiki.openstack.org/wiki/NetworkingGuide/TOC 14:11:08 thx 14:11:13 yeah, he got to it first 14:11:29 any other blueprints/specs to talk about? 14:11:31 #link https://wiki.openstack.org/wiki/NetworkingGuide/TOC 14:11:41 eglynn: do you want to talk about the ceilometer work? 14:11:55 annegentle: sure 14:12:04 go ahead 14:12:07 annegentle: in the context of the ML thread? 14:12:53 eglynn: whatever you want to talk about, really 14:12:54 OK, so my goal there was to minimize the learning curve required for non-doc-team members to contribute documentation content 14:13:18 as we have a TC-mandated action to beef up the admin guide for ceilometer 14:13:40 so the gist of the discussion for those who missed it was ... 14:14:32 (a) there is a new light-weight RST-based contribution model being trailblazed for the heat HOT guide 14:15:02 (b) that model would not be applicable to the ceilometer case as we're contrib'ing content as a new chapter to the admin guide 14:15:28 (c) we'll micro-streamline by clarifying exactly when in the workflow the doc polish should be applied 14:15:52 yep that's a good summary 14:16:10 on the latter point, that "exactly when" moment is when the porject-team contributor removes the WIP -1 flag on the patch 14:16:11 would it perhaps make sense... 14:16:28 we'll aim to be proactive about doing that and give you folks a heads-up 14:16:32 right, a signal I messed up :( 14:16:33 NickChase: /me is all ears 14:16:45 to treat the ceilometer chapter as a separate rst-based "book" that can then be included in the admin guide, since it's self-contained? 14:16:53 annegentle: np! we're weren't 100% clear on the workflow either 14:17:12 NickChase: we toyed with that idea too 14:17:31 NickChase: generally I think RST makes sense for the user guide/ hot templates since it's what we ended up designing and discussing 14:17:50 the ceilometer request came in later 14:17:56 not that timing is everything at all 14:18:02 and I'm interested in easing contributions 14:18:18 just not sure it's good to experiment with both the user guide and admin guide 14:18:30 but maybe I'm splitting hairs, it's okay, you can tell me :) 14:18:39 well, the HA guide has been using RST for some time 14:18:47 so not sure how much of an "experiment" it would be, unless I'm missing somethiong 14:18:49 NickChase: no it started as asciidoc and is now docbook 14:19:21 NickChase: but that's a whole book, also, not an inserted chapter 14:19:40 NickChase: but I like how we're thinking about this, just trying to contain the experiment I guess? 14:20:32 I can understand containment. and I missed the fact that it's now docbook. :) 14:20:46 :) 14:20:47 ... have a suitable standalone guide/book for all projects, that all are also possible to be put together.. and have the stand alone viewable at .docs.openstack.org -- easier to find. ;) 14:20:49 but the chapter vs book thing I though is not an issue. 14:21:04 annegentle, NickChase: so I would be happy to be part of an extended experiment, but will hew to the domain experts' judgement on this 14:21:04 that said, where DO we stand on what the ceilometer content is being produced as? 14:21:08 NickChase: I really want to move to a page model, less book 14:21:11 NickChase: but it's early 14:21:17 NickChase: it's docbook patches now 14:21:21 k 14:21:24 NickChase: mostly set to WIP 14:21:40 thanks for all the good discussion eglynn much appreciated 14:22:03 should probably move on to next topic 14:22:04 NickChase: yep, we've some WIP docbook-based patches up, as we learned the ropes around the workflow 14:22:13 #toipc Networking Guide and swarms 14:22:30 eglynn, Ildiko (sp?) is doing great work! 14:22:31 #link Networking Guide and swarms 14:22:38 AJaeger: ++ 14:22:48 er I can't operate a meetbot this morning 14:22:53 #topic Networking Guide and swarms 14:22:56 #link http://openstack-swarm.rhcloud.com/ 14:23:14 That one is in Brisbane, Aug. 9 (This Saturday!) 14:23:42 which is a friday night for US folks... 14:23:48 Ayup they are the futurists 14:24:12 #link http://www.meetup.com/Australian-OpenStack-User-Group/events/198867972/ 14:24:28 Then shortly after in the US, after the Ops Meetup, we'll meet for a day in San Antonio 14:24:53 #link https://etherpad.openstack.org/p/neutron-docs-juno 14:25:09 #link http://www.eventbrite.com/e/openstack-ops-mid-cycle-meetup-tickets-12149171499 14:25:30 that thing for 2 days? 14:25:40 The dates are 8/25-8/26 for the Ops meetup, then we're meeting in a bunker for docs work on 8/27. 14:25:45 sounds awesome 14:25:50 sounds dark 14:25:59 sld: hopefully it'll fit your schedule! 14:26:02 AJaeger: hehe 14:26:10 AJaeger: actually it's pretty light, in a renovated shopping mall 14:26:23 but the cloud was developed in the basement, with no hint of irony whatsoever :) 14:26:31 annegentle: for the 27th - when/where is that at? 14:26:36 bunker reminds me of cold, wet and dark - thinking world war II... 14:26:44 AJaeger: not far from the truth 14:26:44 lol 14:26:55 sld: SAT6-2325-Presidential Suite conference room 14:27:07 #info Docs swarm this Saturday in Brisbane 14:27:21 #info Neutron doc day after Ops Meetup in San Antonio 8/27, SAT6-2325-Presidential Suite conference room 14:27:21 time? 14:27:45 sld: 9:00 am start 14:27:49 k. 14:27:58 sld: phil_h might have more details if he's an early bird though! 14:28:12 sld: hopefully we can overlap some 14:28:13 yeah, he gets in a little after 6, usually 14:28:17 i hope :) 14:28:24 #topic Website design and contributor experience work in progress 14:28:42 so I have a meeting scheduled next week with HP to try to get that Gerrit web UI going 14:28:48 I'll get a spec done once I know more 14:29:00 I'm kind of excited 14:29:24 #topic HOT Template Guide in progress; Gauvain on vacation 14:29:44 That's just a general FYI 14:30:14 #link https://review.openstack.org/#/c/111565/ 14:30:24 that's the Work In Progress patch for the curious 14:30:57 #topic Architecture and Design Guide proof print on the way; meeting with wider content team 14:31:14 I've got a review in progress for the landing page to make it similar to the Ops Guide and Security Guide 14:31:30 #link https://review.openstack.org/#/c/112070/ 14:31:39 I'm working with the Foundation on a promotion plan 14:32:04 You all probably know already there's a Content Team for the Foundation itself, separate from docs, but Docs PTL is involved 14:32:26 since there's a push for enterprise content we'll discuss how to promote and get more contributions 14:32:46 Ah berendt just saw your request for arch 14:33:03 I think it's ok, arc has to stay since I stored the epub there (though we can always redirect) 14:33:10 easy to fix though 14:33:36 related to the landing, is berendt's patch for a templatized set of html flat files 14:33:50 and sld looking to consolidate js 14:34:16 Static site generator for your perusal: 14:34:17 #link https://review.openstack.org/#/c/112239/ 14:34:47 I'll review later today ok berendt? 14:34:59 Like how we're thinking more about this and the page-based thinking, thanks all 14:35:01 we should first choose a site generator. there are a lot of them (listed at https://www.staticgen.com/). 14:35:16 berendt: for sure 14:35:22 should be discussed inside the review request or on the mailing list. 14:35:46 berendt: sure. I had thought of Jekyll or Middleman based on conversations in the last year or so 14:36:00 berendt: and it may tie into the site design and gerrit / contributor design 14:36:08 berendt: so we might not decide right away 14:36:16 berendt: though man, do we need it! 14:36:21 that's ok 14:36:34 berendt: that's a very useful site 14:37:02 once I have the proof print (hopefully this week!) we can do the promo work on the Arch Guide 14:37:07 It's really pretty :) 14:37:12 that green cover just pops 14:37:33 I also like to start thinking we'll have a book path and a page path for our content 14:37:41 choose certain paths for certain content 14:38:03 Ok, definitely hope there are people around who want to talk about the next topic 14:38:07 #topic API docs: replacing WADL links in dev refs 14:38:17 #link https://review.openstack.org/#/c/111436/ 14:38:21 I'll talk about anything. :) 14:38:31 NickChase: nice, always good to have opinionated people around! 14:38:42 :) 14:38:59 I may not say much, but I'm still here too. ;-) 14:39:01 I've gathered data over the last year or so about API docs and contributions, and WADL is a really tough sell. 14:39:03 :) 14:39:14 If you look at the contribution stats, Diane was the main contributor 14:39:32 wadl is horribad 14:39:34 she's still contributing because she's AWESOME but it's not her full-time job any more, she's at ebay 14:39:42 wadl fills a specific need 14:39:57 but, I think that need is best met with the API reference and not embedded in books 14:40:04 especially when those books don't include parameter output 14:40:19 so my proposal is to remove WADL from the def refs and keep it only for the API Complete Reference 14:40:30 any one have concerns? 14:40:36 only cheering? 14:40:43 lol 14:40:58 annegentle, I think all of us try to avoid WADL ;( So, any removal is great ;) 14:41:03 AJaeger: :) 14:41:07 exactly 14:41:21 AJaeger: I know it has its place to describe APIs, but there are alternatives we need to investigate 14:41:32 Swagger, RAML, etc 14:41:58 esp. if no one plans to assign a full time person just to WADL maintenance 14:42:06 really, I think we are going to have trouble with anything that requires someone to learn a new format 14:42:25 I wish there was some way to just automatically extract from the code......... 14:42:27 NickChase: yeah but they all are a new format for describing REST API (WADL is actually the oldest) 14:42:37 NickChase: but then we don't know if the code is right 14:42:41 NickChase: so that's dangerous 14:42:50 NickChase: we need to serve users 14:43:06 hang on: if we're documenting the code, the code is ALWAYS right -- even when it's wrong. 14:43:26 NickChase: ha. Unless the code is wrong and we break tens of thousands of clients 14:43:37 world domination? ;) 14:43:44 Ok last topic 14:43:48 ha AJaeger :) 14:43:51 #topic Changing review team for clouddocs-maven-plugin 14:43:57 AJaeger has a good idea here 14:44:05 #link https://review.openstack.org/#/c/106923/ 14:44:10 when is that going to go through? 14:44:17 sld: Never ;) 14:44:21 lol 14:44:26 Basically making the docs-core team have +2 on clouddocs-maven-plugin 14:44:32 that would be cool 14:44:34 so that there's not just one person with +2 14:44:37 exactly 14:44:43 i like the logic behind it... it just makes sense. 14:44:47 yeah me too 14:44:53 so, adding the docs-core team as group to clouddocs-maven-plugin - so keep Sam in and add us 14:45:06 This only needs a change to the ACL, no patch 14:45:16 AJaeger: yep. And there may be one other Racker, Thu Doan, we can add to the clouddocs-maven-plugin 14:45:21 AJaeger: ok so do I abandon https://review.openstack.org/#/c/106923/? 14:45:28 Sure, I love to see more experts! 14:45:32 * annegentle is not sure of exact next steps 14:45:47 annegentle, just ask Sam or the infra team to add us to the ACL 14:45:59 Okay good it, is that a patch I can do? 14:46:14 I've told Sam about the idea 14:46:25 annegentle, the same way you add cores to docs-core... 14:46:31 Ask the infra team 14:46:32 ah got it, in gerrit 14:46:54 yep - I guess Sam has the permissions to do it 14:46:57 #action Anne to ask Sam Harwell to add docs-core to the clouddocs-maven-plugin review team 14:47:07 ok, that's all I got! 14:47:11 #topic Open discussion 14:47:30 please help with bug triage and bug fixing! 14:47:38 should we have another bug squashing day? 14:47:43 heh 14:47:44 +1 14:47:50 AJaeger: oh yes I like the idea 14:47:52 yes 14:47:54 AJaeger: September? 14:48:16 August is vacation month, so September... 14:48:24 I'm for september when we know what bugs are in for install 14:48:34 what is code freeze date? 14:48:37 that is in september. 14:48:38 hopefully we'll have some juno packages by then 14:48:43 am on vacation week of Sept 15th 14:49:04 hopefully we wont see a lot of changes for the 'core' services in juno 14:49:15 rc-1 comes out early Sept 14:49:30 #link https://wiki.openstack.org/wiki/Juno_Release_Schedule 14:49:34 DVR in Juno Neutron concerns me 14:49:37 for icehouse we saw packages at milestone 2 14:49:43 Sept 4 string freeze 14:49:46 rc1 - september 25th 14:49:51 yep 14:49:53 Install from source!!!! 14:49:54 yep what sld said 14:49:55 was just looking at that page too. lol 14:49:59 phil_h: no thanks 14:50:03 phil_h: I'm SO there! :) 14:50:05 phil_h: ahh 14:50:21 phil_h: your experience seems too painful to put into the install guide 14:50:21 phil_h: yeah the TC is also concerned about DVR 14:50:37 ok I feel stupid but what's dvr? 14:50:38 soinstalling from source is not difficult and I am working on documenting on how to do it 14:50:45 what is dvr? 14:50:54 aside from digital video recorder, that is. 14:50:58 distribute virtualo router 14:51:14 makes Neutron L3 ha 14:51:18 an ha-ish router? 14:51:21 ahhhhhh ok. 14:51:24 that would be cool 14:51:38 critical for neutron to meet nova network parity 14:51:39 think of it kind of like vmware's dist virtual switch of sorts 14:51:39 you're concerned about how to document it, or whether it works? 14:51:59 sld: distributed virtual router, I had to ask in the TC meeting :) 14:52:06 heh 14:52:07 if neuton does not achieve nova network parity is goes back to incubated 14:52:11 NickChase: upgrade, migrations, http://eavesdrop.openstack.org/meetings/tc/2014/tc.2014-07-29-20.02.log.html 14:52:18 phil_h: I believe so 14:53:00 September 4th week would be good for bug squash day 14:53:14 Maybe Sept 5th? 14:53:18 kmesterly the Neutron PTL told us that on a conf call a few weeks back 14:53:21 it's a Friday so we'd lose Aussies 14:53:43 phil_h: yeah I haven't started thinking about doc ramifications yet... 14:53:59 I mean, I'm thinking about them, of course. 14:54:01 phil_h: have you tried it yet? 14:54:12 phil_h: if that happens, what will happen with networking? neutron just goes away and we are left with nova-network again? 14:54:13 The DVR code has merged into trunk so I beleive it will be ok 14:54:17 ah 14:54:18 ok 14:54:43 There are a few bugs with DVR but it is coming along 14:54:43 annegentle: that thursday then? 14:54:57 sld: or we could do the Tues. after Sept 4th? 14:55:10 9/9 seems like a good day to squash bugs! 14:55:12 so we need to document DVR; I believe we are on our way to doing that. I am supposed to get a few candidates for HA work today or tomorrow 14:55:15 AJaeger: any thoughts on which weekday? 14:55:36 I can't do 9/2-3 14:55:36 annegentle, all are bad - Just throw a dice :) 14:55:36 NickChase: yeah my sense is that the networking doc plans are considering that 14:55:41 but still, priorities priorities 14:55:50 we'll need a networking guide no matter the neutron outcome 14:56:06 phil_h: ok good to know. I'd prefer to avoid 9/4 and 9/5 due to the gate possibly being slow 14:56:08 They need us to doc DVR to reach parity 14:56:09 we need a day for a fast gate 14:56:15 phil_h: ok good to know 14:56:32 9/1? or the next week? 14:56:34 phil_h: we can make that happen 14:56:43 9/1 14:56:45 phil_h: especially if you can brain dump 14:57:05 Will try but right now I don't know much 14:57:11 phil_h: heck, in a worst case scenario, if you can brain dump I can write it 14:57:20 phil_h: I'd rather do bug triaging after a freeze 14:57:30 we have a couple of weeks before we need to panic 14:57:33 I liking 9/9 14:57:35 I will be installing from source in the next couple of weeks and then I will know more 14:57:41 k 14:57:45 do that many bugs relate to juno though? 14:57:46 AJaeger: do you want to take point on bug squashing? 14:57:55 9/9 works for me 14:58:01 I'll try to 14:58:01 Sam-I-Am: I've been triaging API docs and for those, not too much. 14:58:09 9th should be fine 14:58:16 seems like a lot of our bugs have been around a while 14:58:19 Sam-I-Am: for openstack-manuals bugs, I don't know if docimpact backlog is that huge 14:58:31 9/9 is a tuesday so that is middle of my work week, so that sucks.. but i will try and hang for a few hours to try and help. 14:58:33 AJaeger: thank you! I can fill in as needed but want to focus on the design blueprint 14:58:43 sld: we need coverage overnight too :) 14:58:47 lol 14:58:52 sld: ok, sorry, we'll also see what APAC thinks of 9/9 14:58:55 bug day is a 24-hour event 14:59:00 right Sam-I-Am! :) 14:59:09 Wait? What did I just sign up for - annegentle "take point" means what? 14:59:15 Organizing it? 14:59:16 LOL AJaeger! 14:59:22 sounds like it. hehe 14:59:27 AJaeger: Heh. Can you do: write a note to the ML to ask about 9/9 14:59:36 annegentle, yes, I will! 14:59:52 AJaeger: once the date is decided, I think "point" just means "make sure the graphs work" 14:59:59 AJaeger: that's all I'd ask of you :) 15:00:13 dvr meeting starting on openstack-meeting-alt 15:00:22 AJaeger: and let's make sure fifieldt can help, he's such a fast/good bugs triager 15:00:29 okie doke thanks all 15:00:31 #endmeeting