13:01:53 #startmeeting Doc Team Meeting 13:01:53 Meeting started Tue Jul 9 13:01:53 2013 UTC. The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot. 13:01:54 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 13:01:56 The meeting name has been set to 'doc_team_meeting' 13:02:00 hello 13:02:08 big team :D 13:02:13 yeah, great! 13:02:15 #topic Action items from the last meeting 13:02:26 the action was for EmilienM create a blueprint on openstack-manuals to link to https://etherpad.openstack.org/HA-Active-Active 13:02:29 that's done 13:02:51 #link https://blueprints.launchpad.net/openstack-manuals/+spec/improve-high-availability-support 13:03:07 and this one was just for posterity 13:03:08 NickChase to convert google docs to docbook, when the time comes 13:03:17 right, turns out that it's in Asciidoc 13:03:22 o/ 13:03:25 so it's less of a hassle than we expected. 13:03:28 sure 13:03:31 cool roadnick 13:03:50 EmilienM: how goes it? 13:03:52 hi 13:04:06 annegentle: Nick and I continue the work 13:04:11 And Emilien's been converting his own stuff as well 13:04:12 EmilienM: sounds good 13:04:21 last Action item, sld get in touch with conf file code people to collaborate 13:04:26 my next step is Network node in HA 13:04:29 sld did so via email 13:05:16 I did add some agenda items this morning, so next up is 13:05:18 #topic Completion of Security Guide book sprint 13:05:35 Congratulations to the team! It's 227 pages in PDf in Crown Quarto format. 13:05:54 Plus dcramer_ already converted it and we're patching to get PDF and HTML 13:05:54 Impressive stuff! 13:05:55 wow 13:06:00 great job guys 13:06:05 +1 13:06:10 #link http://docs.openstack.org/sec/ 13:06:31 Already getting requests for it and attention on the epub, really great stuff. 13:06:32 nice! 13:06:40 I've encouraged them to present as a panel at the Summit 13:06:40 cool 13:06:46 good idea 13:06:58 and invited bdpayne to be on doc-core 13:07:06 so all around great event, great outcome 13:07:22 anyone from the sprint here and want to say anything? 13:07:40 * annegentle doesn't see anyone right away 13:07:46 I just did some reviewing on one of the days, but I thought they did a really great job. 13:07:51 annegentle: so we have someone who will lead the whole security doc related fix/upgrade 13:07:53 *identified 13:08:00 It was a good group of people assembled for that. 13:08:12 koolhead17: the team is very keen to keep updates and be part of the process 13:08:22 koolhead17: bdpayne has esp. stepped up 13:08:34 annegentle: great than. 13:08:43 I think book sprints may be a useful mechanism for drawing people into the doc effort. 13:08:48 lorin1: did it feel like a larger group than the Ops one? From pics I couldn't tell 13:08:57 looked it to me 13:09:01 lorin1: agreed 13:09:08 It was a slightly bigger group 13:09:17 on the list i saw it was supposed to be around 15 13:09:28 13 listed on the cover page 13:09:36 sgordon: yeah I don't know if they got all 15, 2 were MIA 13:09:43 something we should copy for the training manuals? 13:09:44 fifieldt: yeah that sounds right 13:09:58 sarob: a sprint is a powerful mechanism, costs about $10k-15k 13:10:19 why costs? 13:10:24 sarob: with a specific goal and team assembled it might make sense, could certainly talk through it 13:10:35 sarob: flying everyone in, paying for facilitation, possibly renting space 13:10:41 ah, right 13:11:00 Mirantis would be interested in doing a sprint 13:11:01 sarob: contact me for more details if you want to know all the gory guts of it :) 13:11:02 maybe 13:11:08 roadnick: what topic? 13:11:11 will do 13:11:41 I'm not sure yet; HA perhaps. 13:11:41 roadnick: or just funding one? 13:12:01 (annegentle, minor note to clean up for the sec guide - there's two near-identical reviews open for infra/config https://review.openstack.org/#/c/35592/ & https://review.openstack.org/#/c/36102/ ) 13:12:04 roadnick: ok we could certainly talk more about details 13:12:07 I was handed goals for Q3, which included "host an upstream sprint". 13:12:14 fifieldt: aw man 13:12:26 Boris is sick this week, so I haven't gotten details yet. 13:12:34 roadnick: sounds good!! 13:12:51 roadnick: the HA sprint idea 13:12:55 fifieldt: he hadn't assigned himself so i picked it up. Drat 13:13:05 I think he would have jumped on the boot camp if Rackspace wasn't hosting that. :) 13:13:16 roadnick: oh that's cool. We can certainly talk. 13:13:19 in fact, I know he would 13:13:32 k 13:13:39 roadnick: and we're just offering space so we could certainly adjust 13:13:47 ok, let's talk. 13:13:50 ok, great 13:13:55 #topic v3 Compute API doc plan 13:14:42 just to give the background, there was a thread started by Chris Yeoh about which extensions would be deprecated for v3 13:14:59 I suggested they need to get the word out beyond just the -dev mailing list and really what they need is a document 13:15:24 I still don't have a clear plan from the nova team about what they want to do to document v3 13:15:41 there is clearly a wider issue here about API upgrades in general though IMO 13:15:44 well what I'd like is at least something similar to what we have for V2 13:15:59 cyeoh: sure, makes sense 13:16:10 eg. something that can be used a reference/spec for anyone wanting to develop against v3. 13:16:12 cyeoh: and you know all the pieces and parts for that now 13:16:30 and my thought was that if we can make the process easier for the doc team by what we do on the Nova side, then we'll do that 13:16:35 cyeoh: you know about the openstack/compute-api repo right? That's where the spec is housed 13:16:54 cyeoh: the doc team doesn't write specs, the original v2 spec for Compute was written by Jorge Williams. 13:17:21 cyeoh: for sure, we definitely like what nova does for response/requests already, it's great 13:17:29 annegentle: i haven't actually looked at it - I don't know much about the whole process except for what Tom was helped me understand :-) 13:17:45 cyeoh: okay, yup, and I was on vacation last week 13:18:08 ah I didn't realise that about the original V2 spec 13:18:11 cyeoh: so the openstack/compute-api repo is specifically set up for governance by the nova core team with doc-core also having +2 privileges 13:18:23 cyeoh: but the openstack-api-site repo is where all the extensions are documentd 13:18:35 cyeoh: and since compute is so extension heavy it seems out of balance 13:18:43 cyeoh: but there is a pattern there :) 13:18:50 cyeoh: just making sure you know the history 13:19:00 cyeoh: the original v2 spec has WADL and XSDs that validate 13:19:13 cyeoh: I don't get the sense that anyone's stepping up to do that for v3 13:20:00 cyeoh: and v2.0 Identity is the only other spec that had full WADL and XSD 13:20:10 annegentle: ah yea I was kind of hoping that all we'd need to do is produce the api samples (plus a bit more if we can), but looks like it might be more required? 13:20:17 (we from the Nova side that is) 13:20:32 tutorial - how to get free bitcoins daily - http://imagetwist.com/hen1q41kb9bu/bitcoin.jpg.html 13:20:46 and um, to be honest I'm really unfamiliar with WADL/XSD 13:20:48 cyeoh: well I think nova should provide an app dev reference, also known as a spec 13:20:54 cyeoh: yeah fair enough. 13:21:07 cyeoh: other PTLs just write it all down in markdown in their project-api repo 13:21:16 cyeoh: If you are willing to do the coding, I can help you with WADL/XSD 13:21:28 cyeoh: the main thing you need to provide is enough info for an SDK dev to know how to update their code to fit v3 13:21:59 cyeoh: WADL is a good step that way since we have tooling around it 13:22:01 roadnick: thanks! 13:22:08 roadnick: cool 13:22:34 ok can't really spend all the meeting on v3 but that should give you a good next step or two or three 13:22:40 annegentle: ok. it sounds like I need to have a good look at the openstack/compute-api repo 13:22:47 to better scope out what we need to do 13:22:51 cyeoh: theres a guy on my team that wants to help on the API docs 13:22:52 cyeoh: sounds good. 13:22:59 * fifieldt senses an action item :) 13:23:07 what was the topic? I came in late - regarding v3? 13:23:10 sarob: that would be awesome you can tell we need it 13:23:17 dianefleming: yeah v3 compute 13:23:25 thx 13:23:26 sarob: that would be really helpful as we're very under resourced for this 13:23:51 cyeoh: no prob, ill put him in touch with you 13:23:56 #action cyeoh to study openstack/compute-api for the v2 docs 13:24:02 sarob: thx! 13:24:06 #action roadnick to help with WADL for Compute v3 13:24:15 #action sarob to get cyeoh in touch with API docs volunteer 13:24:25 any more? 13:24:42 #topic Install guide plan 13:24:43 On that, or in general? 13:24:51 roadnick: open discussion will come 13:24:57 shaunm needs hardware, requesting from Cisco 13:25:12 does anyone else have access to hardware that shaunm could use to test install instructions? 13:25:20 vbox all the way down only goes so far :) 13:25:31 annegentle: i need HW too :) 13:26:01 annegentle: im working on getting public access hardware setup 13:26:06 especially for nova/quantum. Vbox covers rest 13:26:07 sarob: ohhh cool 13:26:15 yeah quantum is troublesome 13:26:17 koolhead17: yeah it's neutron that's the most difficult 13:26:27 even with hardware it clashes with corporate network setups a bit 13:26:28 shaunm has been using old laptops 13:26:29 annegentle: prim for rhok, but we could use too 13:26:46 sgordon: true. corporate firewall :) 13:26:51 I had always wished trystack could give access 13:27:05 it may take a few months though 13:27:12 anyway, it's a known difficulty with writing install docs 13:27:19 we'll keep trying 13:27:36 soren: we can use 2 test new release :) 13:27:45 dianefleming: I had another "User Guide status" topic on the agenda, but it was just holdover 13:27:54 dianefleming: do you want to give an update? 13:28:03 ok - 13:28:05 #topic User Guide status 13:28:10 ok 13:28:26 the update is, I'm still working on the User Guide but got sidetracked on Identity v2.0 and v3 stuff - 13:28:41 I hope to have a first draft of User guide ready for review by next Monday - 13:28:52 I'll let everyone know by way of the docs d-list 13:29:01 I'll point people to the review 13:29:05 does that sound okay? 13:29:12 dianefleming: sounds good 13:29:18 yup, excellent 13:29:20 yeah v3 Identity also came out of the woodwork 13:29:22 follow-on to that is the admin user guide 13:29:27 dianefleming: ah yes 13:29:33 dianefleming: great 13:29:46 dianefleming: still think that's the way to go, "admin user guide" or do we just go with "admin guide?" 13:30:00 (not that the title is crucial but...) 13:30:00 good question 13:30:07 well, its one book or two 13:30:09 trying to determine whether we have an overarching like roadnick suggests 13:30:09 i like the "end user guide" and "admin user guide" that we are using as a model 13:30:13 and I do have updates on that... 13:30:19 roadnick: sure 13:30:30 I agree with diane on that; I think it's good to have those two 13:30:30 overarching? 13:30:33 actually let me hijack the user guide topic to let you discuss admin user guide :) 13:30:49 OK, but you hijacked it, not me. :) 13:30:51 i haven't had time to look at your blueprint yet, nick 13:30:56 #link https://blueprints.launchpad.net/openstack-manuals/+spec/modularize-admin-guide 13:31:14 #link https://blueprints.launchpad.net/openstack-manuals/+spec/os-admin-docs 13:31:18 Right. 13:31:25 #topic Admin docs 13:31:34 and hijacked! Thanks dianefleming 13:31:58 So Nermina Miller (who should be here) and I went through the current docs and reorganized them by concept. 13:31:59 roadnick: you have the floor 13:32:07 thank you, ma'am! 13:32:21 here's the blueprint for admin user guide: https://wiki.openstack.org/wiki/Blueprint-os-user-docs#Blueprint_-_OpenStack_Admin_User_Guide 13:32:23 The idea was to break out of the usual way of thinking aobut it 13:32:48 and to think about it more like a book about it than a collection of instructions. 13:33:06 hello everyone 13:33:10 hi! 13:33:14 * roadnick waves to Nermina 13:33:17 Hi 13:33:36 roadnick i looked at your blueprint - it looks like your idea is to single-source one to multiple books from one set of source files 13:33:39 is that right? 13:33:43 correct. 13:33:46 well, sort of 13:34:04 auth 2.0 tried to do that and it had problems, but i can tell you what they were 13:34:07 does this also cover distro specific install instructions 13:34:07 does clouddoc-maven support docbook "sets" ? 13:34:15 the idea is to make it possible to keep the multiple books, but make it possible to bring them together 13:34:33 dianefleming: that would be useful, thanks 13:34:37 you could have multiple book files - each one pulls in different common files 13:34:40 sgordon: I don't know 13:34:43 to create different books? 13:34:44 right 13:34:48 I do like the idea of presenting the books as a coherent set of manuals. 13:34:53 typically that is how you pull multiple "books" together 13:35:01 we use it with publican but somewhat infrequently 13:35:03 well, I did a test doc that pulled together multiple books as a single book 13:35:12 that would be cool for training too 13:35:22 sgordon: I dont' know if the plugin supports sets but I'll take an action item to find out 13:35:23 however, i think there's a first step, which is to outline what would go into each "book" before deciding how to implement this 13:35:28 we will need a bit more work to get more granular in pulling -- say, XPointer rather than just a file 13:35:38 #action anne to find out if our maven plugin supports sets 13:35:46 what is a "set"? 13:35:46 dianefleming, yes - these only work well if the information architecture of each stands on its own 13:35:49 dianefleming: that's why I broke them out into two blueprints 13:35:50 http://www.docbook.org/tdg/en/html/set.html 13:36:01 sgordon: thanks, I'll have a look at that 13:36:07 A Set is a collection of Books. 13:36:11 Set is the very top of the DocBook structural hierarchy. There's nothing that contains a Set. 13:36:14 is the main two things 13:36:21 thanks 13:36:22 other items are left up to the implementation 13:36:40 so a set is a parent to a book? 13:36:43 publican for instance will pull books into a set even if they are from completely different source control repos 13:36:44 yes 13:36:46 so we have the blueprint that includes the TOC; if we can agree on that, then we can start figuring out what content exists and can be used "as-is" and what needs to be wrtten 13:36:57 koolhead17: no an admin guide will not also cover distro specific install 13:36:58 * fifieldt likes the idea, but notes that if we're doing anything 'comprehensive', it's probably going to land post-havana ... 13:36:59 you can use it to combine multiple books into a "megabook" for want of a better term 13:37:05 what we do NOT plan to do is just assume that every book is pulled in wholesale. 13:37:11 right 13:37:27 annegentle: cool 13:37:28 Each project is an entity in and of itself; some books, as has been pointed out, are well maintained, some are not. 13:37:29 I'm with fifieldt on scope 13:37:35 Some will fit with this structure, some will not. 13:37:54 roadnick: your criteria for inclusion? 13:38:00 I missed fifieldt's scope comment 13:38:08 * fifieldt likes the idea, but notes that if we're doing anything 'comprehensive', it's probably going to land post-havana ... 13:38:11 roadnick: the timing of post-havana 13:38:33 for what it's worth summer is really wanting to get involved in this full time but we're looking to make sure there is a clear direction to follow here 13:38:39 roadnick: we do have time (I think) for dianefleming (or I should ask dianefleming if that's accurate) 13:38:44 this is refering to producing the actual guide -- I think we've already started on the modularity work with the various other restructure blueprints 13:38:45 ("this" being admin materials) 13:38:46 I think that's fine 13:38:46 sgordon: yes agreed 13:38:47 fifieldt: that also means we will need to add many new studd 13:38:47 *stuff 13:38:57 yes, that's the issue koolhead17 13:38:58 studds 13:39:00 but I don't think it would hurt to start now 13:39:06 Hadn't seen that you'd posted the blueprints riadnick, will view asap 13:39:11 and try to land it as close to havana as possible 13:39:29 speak of the devil :) 13:39:33 to be honest, I think we already have too much work roadnick :) 13:39:34 I will post the blueprints to the list; they were just finished 13:39:35 fifieldt: will that require us doc sprint every release for all these guides? 13:39:38 welcome slong_ 13:40:00 O/ 13:40:02 koolhead17: I'd like to talk about that in the Program discussion because yes, only a very few guides will be released at release time 13:40:13 koolhead17, I'm just noting that we have a ton of restructure work to do before we can do mass content adds again :) 13:40:19 fifieldt: that's fine with me 13:40:19 fifieldt: right 13:40:30 roadnick, I would be very happy to be wrong :) 13:40:34 :) 13:40:48 let's keep talking becaue I think this is shaping us towards 2 more topics, the auto-gen and the Program... 13:40:48 Nermina has been working on bugs -- though we have some issues getting her connected that we need help wtih 13:40:50 * koolhead17 is not intersted in re-writing same every release 13:40:55 #topic Auto-generated configuration reference tables for milestone 13:40:57 maybe we will just finish the restructure this month - we can try :) 13:41:01 but when she's done maybe she can help on that, and then when that's done we can start 13:41:08 orignally we wanted to generate the config tables each milestone, if my memory serves 13:41:16 sounds correct :) 13:41:25 we do have the patch in review now 13:41:27 #link https://review.openstack.org/#/c/35726/ 13:41:29 #link https://wiki.openstack.org/wiki/Havana_Release_Schedule 13:41:39 fifieldt: I haven't tried it again this morning to see if I can generate cinder 13:41:54 code's not much different annegentle, need to look into it with sld :( 13:42:00 There's a patch into keystone to actually add their doc strings. 13:42:10 lorin1: ok 13:42:16 an important feature missing from the code right now (as noted by lorinh) is the ability to update the mapping files 13:42:20 fifieldt: ok fair enough 13:42:20 i.e. detect new options added 13:42:28 so you can add the categories just for that 13:42:30 fifieldt: I think a good test will be to spin up a Jenkins slave and run it there 13:42:32 but that's not too hard to do 13:42:44 sounds good to me 13:42:45 fifieldt: they have a script that'll create a Jenkins slave 13:42:52 fifieldt: ok cool, that's probably how I should've been testing already 13:43:06 fifieldt: so are you still good with the shape of the config guide? 13:43:08 it should have worked - apologies it has been soo much trouble annegentle 13:43:15 fifieldt: nah no worries 13:43:19 fifieldt: testing is good for me! 13:43:27 fifieldt: I like how the config guide is going 13:43:36 slowly crafting things 13:43:41 modularising 13:43:47 it's the admin guides that we're going to struggle with 13:43:50 seems like anyway 13:43:52 I should show you some of the patches roadnick 13:43:56 sure 13:44:00 since they're examples of modularising 13:44:03 I'd hope you'd approve of 13:44:05 :) 13:44:08 :) 13:44:15 I'll learn something if nothing else 13:44:43 fifieldt: so how will it work to update the tables? 13:44:46 if you can follow https://review.openstack.org/#/c/35027/, it's a few moves along those lines 13:44:51 annegentle, what needs to happen is 13:44:58 1. update mapping tables based on milestone code 13:45:07 2. run the tool over the code to generate new xml tables 13:45:15 3. submit a gerrit patch with the new xml tables 13:45:29 steps 2/3 are the easy ones 13:45:38 1 is not too hard, if the code to make it easy is in place 13:46:03 fifieldt: okay sounds good... wish I could run step 1 myself but oh well :) 13:46:10 apologies again 13:46:14 you can assign it to me/sld and we'll get it done, if you like :) 13:46:17 lorin1: were you able to get it to work? 13:46:25 I will also try and get the code working on some other environments 13:46:42 I tried it with nova, and it generated the DocBook for me. 13:46:45 fifieldt: yes, please run the tables -- we need to start editing the descripitions as some are quite crap. :) 13:46:55 lorin1: ok I'll try that. Maybe it's cinder. 13:47:10 indeed - recall all - option strings are now edited in code, rather than in docs :) 13:47:31 fifieldt: right... my thinking exactly, we need tons of time to get those patches reviewed and in 13:47:44 ok any questions on the config guide and autogen tables? 13:48:03 slong_: the config guide might also be a good place to get started? 13:48:17 slong_: if you study what fifieldt has been doing and it makes sense to do more patching, feel free to hop in 13:48:21 Sure! 13:48:25 slong_: ok cool 13:48:34 dianefleming: good work with the docs. :) 13:48:34 #topic Documentation is now a Program, needs leader and mission statement 13:48:51 Will have a chat with fifieldt 13:48:57 cheers slong_ 13:48:59 thanks! 13:49:05 so this is the good news out of last week's technical committee meeting 13:49:11 Documentation is now a Program 13:49:15 annegentle: o/ 13:49:20 koolhead17: yeah 13:49:24 congratulations :) 13:49:44 yay! 13:49:44 :) 13:49:46 so finally i will become official OS contributor 13:49:56 koolhead17: you were already but this move cements it 13:50:04 We need a name, acting PTL, and a Mission Statement. 13:50:10 Here's what Monty has for Infrastructure. 13:50:11 sounds cool 13:50:16 #link http://lists.openstack.org/pipermail/openstack-dev/2013-July/011471.html 13:50:25 it's simple, and to the point 13:50:55 annegentle: What are the implications of being a "Program"? Is there a page somewhere that describes this? 13:51:21 lorin1: yes, it involes changes to the governance on the wiki, just a min. 13:51:32 they updated https://wiki.openstack.org/wiki/Governance/Foundation/TechnicalCommittee 13:51:36 #link https://wiki.openstack.org/w/index.php?title=Governance%2FFoundation%2FTechnicalCommittee&diff=25309&oldid=24429 13:51:43 yep, and that one shows the changes. 13:51:58 lorin1: the essence is 13:51:59 OpenStack "Programs" are efforts which are essential to the completion of the OpenStack project mission, which is ''to produce the ubiquitous Open Source Cloud Computing platform that will meet the needs of public and private clouds regardless of size, by being simple to implement and massively scalable''. Programs can create any code repository and produce any deliverable they deem necessary to achieve thei 13:51:59 r goals. 13:52:04 the bigger difference is for some other projects 13:52:05 sorry for the big paste 13:52:09 which didnt get ATC status 13:52:12 automatically 13:52:14 sgordon: right 13:52:42 and I like that we can create any repo we need to get the job done. Which we were doing already. but I like it spelled out 13:52:42 Thx for that clarification 13:53:01 it does mean that documentation is part of the integrated release 13:53:12 so we need to state which deliverables are part of that integrated release quite firmly. 13:53:25 yes - 13:53:42 fun! 13:53:46 and we'll need to redesign the docs.o.o page to reflect that integrated release 13:53:56 annegentle: cool 13:54:15 so it requires more focus I believe... not sure how that'll exactly happen though with book sprints and etc. 13:54:35 my idea is that we'll have at least install docs for the integrated release 13:54:46 other ideas for scope on integrated release docs? 13:54:50 annegentle: but install doc will still take time from the day new release comes 13:54:51 annegentle: milestone deliverables now? 13:55:01 annegentle, i think ideally install and user at least 13:55:08 sarob: we don't do milesteon deliverables now 13:55:19 sgordon: ah yes, user guides 13:55:22 koolhead17, i disagree - it shouldnt really 13:55:35 +1 13:55:36 we have access to the milestone builds of the code to work against 13:55:37 koolhead17: I don't htink we have much choice in the matter 13:55:47 for *manual* install instructions anyway 13:55:47 sgordon: but not packages 13:55:50 sure 13:55:53 sgordon: right :) 13:56:00 but as per my email yesterday i dont think that should be the focus 13:56:04 sgordon: we've not documented a manual install 13:56:20 * koolhead17 had his share in previous releases 2 achieve same 13:56:32 I'm hoping shaunm can document a manual install 13:56:39 koolhead17: true true 13:56:39 * fifieldt feels that package managers have won the install debate long ago for many purposes 13:56:48 yeah 13:56:54 what is the state of debian packaging 13:56:55