13:00:44 #startmeeting docwebteam 13:00:45 Meeting started Tue Apr 9 13:00:44 2013 UTC. The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot. 13:00:45 rather than #startmeeting Doc Team 13:00:46 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 13:00:46 oh, ok 13:00:48 The meeting name has been set to 'docwebteam' 13:00:50 my bad 13:00:54 no worries :) 13:01:00 I guess I do what I'm told! 13:01:10 annegentle: :P 13:01:31 #topic Action items from the last meeting 13:01:38 action: fifieldt_ send a note to discuss grizzly priorities on the OpenStack mailing list 13:01:42 That's done 13:01:43 done 13:01:51 action: annegentle to ask Doc Tool team about Crown Quarto PDF output 13:01:58 unfortunately, not a reply, and little response in the bug assignment department 13:02:09 Yeah I noticed that... 13:02:11 Also done, and we can output Crown Quarto to our PDF 13:02:16 yay 13:02:28 but they're already using DocImpact for Havana. sigh. :) 13:02:38 action: annegentle to send a call to action to help with grizzly doc bugs 13:02:47 So, I think I did that? But maybe to the -doc list? 13:02:54 or? 13:03:06 I have Grizzly doc bugs as an entire topic of its own so we can talk more then 13:03:07 you did mention it in your -doc newsletter 13:03:09 one more action 13:03:14 cool 13:03:17 action annegentle to add info about pom.xml change for 1.7.1 to wiki 13:03:24 So this is halfway done, definitely need more info. 13:03:35 I'm going to reassign it to me :) 13:03:43 got a link? 13:04:02 #action annegentle to add more info about 1.7.2 to the HowTo wiki page 13:04:17 fifieldt_: what I did so far was to update the Conventions page about image markup 13:04:24 #link https://wiki.openstack.org/wiki/Documentation/Conventions#Embedding_images 13:04:26 ta 13:04:29 but there's more to it than that 13:04:36 there's pom.xml stuff too 13:05:01 it's not a huge task though, I'll get to it 13:05:09 ok, I think that's it 13:05:15 for actions 13:05:21 now! Onward! To Grizzly! 13:05:27 #topic Grizzly release 13:05:32 #link https://launchpad.net/openstack-manuals/+milestone/grizzly 13:05:38 #link https://launchpad.net/openstack-api-site/+milestone/grizzly 13:05:56 I have to say I'm having a tough time knowing when to call done done. 13:06:31 understandable 13:06:39 My sense is that the majority are quantum and swift deficits. Tom, what's your sense of it? (fifieldt_) 13:07:03 And, I don't know if the install docs are releasable when the packages aren't completed? Thoughts? 13:07:03 I'm a big believer in testing 13:07:17 so right now those bugs are mostly derived from DocImpact 13:07:25 The broken script links are certainly getting comments in the docs :) 13:07:34 I think once someone has run through the install docs and verified they work 13:07:43 fifieldt_: yeah I agree with testing the install docs. 13:07:44 then that's release goodness 13:07:51 annegentle: that install using nova-network is not there anymore :( 13:08:04 koolhead17: where's there? 13:08:09 i was thinking to re-test and modify it 13:08:13 appendixB 13:08:15 one 13:08:36 for the 'reference' guide, that's something that can go once there are no obvious errors/pitfalls left - i.e. there';s only new features left to add 13:08:47 ubuntu installation with openstack & we had a APPENDIXB 13:09:02 which covered single machine deployment with nova-network 13:09:29 #link https://bugs.launchpad.net/openstack-manuals/+bug/1133699 13:09:31 Launchpad bug 1133699 in openstack-manuals "grizzly: Update Appendix B OpenStack Deployment Guide" [Medium,In progress] 13:09:37 koolhead17: yeah we got rid of Appendix B it was causing too much maintenance headache and mismatch 13:10:08 annegentle: ok. 13:10:11 I want to talk alot about install doc in the "refactor" session next week 13:10:23 annegentle: so do i :) 13:10:28 yeah 13:10:32 I figure we all do :) 13:10:38 ahaha 13:10:48 i would say it will be too much of clean up 13:11:02 it's a big job 13:11:07 but I have ideas :) 13:11:15 me too :) 13:11:21 so I sense others in the community are going to create the one-pagers 13:11:23 for install 13:11:34 it's more important that ours is a tested path for "production-like" enviros 13:11:57 So, are we okay with "once install is tested and packages are out, release?" 13:12:05 or is there another set of criteria we need to be above? 13:12:10 for install guide, that sounds reasonable 13:12:25 for the 'reference' guide, I think that can go once there are no obvious errors/pitfalls left - i.e. there';s only new features left to add 13:12:49 What's the 'reference' guide? 13:12:56 is that the API reference page? 13:12:56 'compute admin' 13:13:02 not the API one 13:13:02 oh! 13:13:05 sorry for confusion 13:13:10 no problem! 13:13:36 speaking of which - api ref for grizzly - all good? 13:13:48 fifieldt_: I think so -- ladquin or writerDiane do you have input? 13:13:59 I'm still working through the bugs 13:14:08 ladquin wrote a lovely end-of-internship report 13:14:17 ladquin: thank you SO much for all your hard work! 13:14:21 I'm finishing the Quantum section, which samples took me a lot more that expected 13:14:34 annegentle, :) 13:14:37 there are some reviews waiting at 13:14:38 my pleasure 13:14:39 #link https://review.openstack.org/#/q/status:open+project:openstack/api-site,n,z 13:14:53 ladquin and writerDiane Ok, keep on trucking then. 13:14:55 +1 API is hardd 13:15:22 fifieldt_: so how much do you think it would take for the reference guide with all the conf options to be "done" 13:15:39 hi ladquin writerDiane 13:15:44 hi! 13:15:45 ok, so config options that were reported with doc impact are more or less done 13:15:45 fifieldt_: and is that a new guide (standalone) or are you saying it's in other guides? 13:16:03 they were the easy bugs to solve 13:16:06 annegentle: are they the one working as interns 4 the doc stuff under gnome internship? 13:16:08 * koolhead17 is confused 13:16:10 fifieldt_: impressive 13:16:16 but we're still missing many - 13:16:22 for that I think the autogenerate is the solution 13:16:27 koolhead17: ladquin is just now finished with her GNOME OPW internship, writerDiane works with me at Rackspace 13:16:32 doing it manually is going to be a pain 13:16:37 ooh okey 13:16:47 hi, koolhead17! 13:16:49 we're growing koolhead17 :D 13:16:57 fifieldt_: yay!! 13:16:59 writerDiane: koolhead17 is Atul, has been working on OpenStack docs since wayyyy back when! Cactus, right? 13:17:08 yes :) 13:17:17 oh! hi koolhead17 13:17:23 fifieldt_: I completely agree on the autogenerate. 13:17:23 writerDiane: salute 13:17:34 fifieldt_: ok, so what I hear is, release Grizzly with the config we've got 13:17:41 fifieldt_: after install is tested 13:17:51 roger 13:17:53 annegentle: fifieldt_ my 1 line suggestion would be we are interested in doing things from scratch :) 13:17:59 make it plug and play/moduler 13:18:20 'course ;) 13:18:30 Is that possible in about two weeks even with the Summit? Or a month from now? 13:18:33 that way we exactly know in all our docs what needs to be modified everytime new release comes 13:18:38 5/9? or end of April? Hm 13:18:56 I think when the cybera guys get through it is a good timeframe 13:19:09 annegentle: also we need to get guys guys from RH/Ubuntu/Suse community to help us a bit 13:19:15 indeed 13:19:21 if we are pushing the doc with the distro 13:19:35 it would be great if they do testing for us 13:19:36 :) 13:19:46 just a suggestion 13:19:54 koolhead17: yeah I constantly reach out 13:20:04 annegentle: probably we should have a doc session title "vedors & openstack docs" 13:20:08 koolhead17: will do more in person next week 13:20:12 where we can address some of these issues 13:20:15 koolhead17: heh and if no one came? :) 13:20:23 I think a more individual approach is better 13:20:28 rather than a session 13:20:30 annegentle: okey 13:20:40 i am saying this because tomorrow 13:20:40 we/"the foundation" should be contacting people and roping them in? 13:20:53 cinder driver folks would like to have stuff added 13:20:56 yeah this is an ongoing bit of relationship building 13:21:03 so kind of we need to know whom to approach 13:21:09 4 helping hand 13:21:23 so am wondering if we should have session addressing this need 13:21:27 just a suggestion 13:21:28 :P 13:21:47 koolhead17: yeah I get it, just saying this is what we already do :) 13:21:54 cool 13:21:55 :) 13:21:57 koolhead17: so it feels a little like you're telling me I'm not doing my job 13:22:10 let me know whom to trouble 4 redhat installation help 13:22:22 annegentle: oops not at all 13:22:40 koolhead17: it's okay, just telling you how I'm perceiving it :) 13:22:52 annegentle: apology for that :( 13:22:55 koolhead17: but definitely we need more relationship building and "I" don't scale 13:23:05 koolhead17: so we have to continue to reachout, get names, get to know people. 13:23:15 annegentle: what i simply meant we need to have folks identified whom we can reach out 4 help 13:23:26 annegentle: that is what i meant :) 13:23:35 ah yes! For RHEL install, I have a Racker Phil Hopkins who wants to take the Basic install guide and make it RHEL ready. 13:23:47 cool 13:23:53 awesome 13:23:54 koolhead17: Yeah, it would be great to designate "maintainers" for docs 13:24:18 koolhead17: so far I don't sense that much responsibility for individual docs, well maybe in some cases. Hm, it's a good question. 13:24:46 I think it's hard to "own" a doc 13:24:47 #agreed Release Grizzly docs after install is tested and packages are available. Approximately in 3-4 weeks. 13:24:48 annegentle: if you can see current questions in maling list about basic redhat install 13:24:53 in the community sphere - 13:25:04 writerDiane: yeah I don't see it, yet. 13:25:18 koolhead17: yeah I think Phil's work will help with that 13:25:22 maybe this is a good discussion to have via ML or an etherpad - thresh out a strategy ? 13:25:30 it might be interesting to get feedback from people at the summit about why they don't contribute to doc - there might be reasons we don't know about 13:25:44 "strategy for increasing contribution" 13:25:57 fifieldt_: yes exactly 13:26:04 fifieldt_: for install doc, it has been interesting to see install docs pop up individually but the "official" ones lightly touched 13:26:10 writerDiane: yes 13:26:22 agree 13:26:34 yes 13:26:40 writerDiane: yes, I think I know the reasons (toolchain is hard, I don't know enough to speak authoritatively, I don't have an enviro) 13:26:52 writerDiane: not that those are all! There are many is what I mean :) 13:27:09 #link https://etherpad.openstack.org/IncreasingDocContributions 13:27:17 nice, fifieldt_ 13:27:33 yes, toolchain is hard but also the environment is a little unsettling - people patching patches, etc - not clear ownership (which is by design) - but that can be unsettling 13:27:39 so that leads naturally into our next topic 13:27:41 #topic Refactor docs discussion - review blueprint before Summit 13:27:54 cool 13:28:04 #link https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation 13:29:15 It'll be easiest to talk about it in person next week but wanted to be sure you all have the ideas ahead of time 13:29:24 #link https://wiki.openstack.org/wiki/Blueprint-restructure-documentation 13:29:42 LGTM :P 13:29:51 fifieldt_: hee 13:30:08 fifieldt_: devil's in the details 13:30:17 :P 13:30:23 Okay 13:30:30 moving on in the interest of time 13:30:32 #topic Docs-draft work for easier reviews 13:30:55 for one of ladquin's major contributions, she has a huge patch to the openstack-infra/config project to add "gate" builds 13:30:56 I couldn't get that approved yet :( 13:31:02 ladquin: yeah I saw that 13:31:14 ladquin: I like jeblair's thinking for patterns, how difficult is it to do though? 13:31:29 #link https://review.openstack.org/#/c/22768/ 13:31:46 fifieldt_: thanks, you were quicker :) 13:31:56 jeblair wanted a little modification and mordred put it in progress, form some reason, so I hopefully be taking care of that today 13:31:57 ladquin: and, how much time do you really have? Should one of us pick it up? 13:32:04 ladquin: wow cool! 13:32:07 annegentle, oh, it's simple 13:32:15 ladquin: sweet 13:32:27 annegentle, but still would like to further discuss it with him 13:33:03 ladquin: ok, great. Let us know if you need one of us to help. 13:33:04 ladquin: hey 13:33:24 mordred: heya 13:33:34 ladquin: I basically started putting things as WIP that it seemed the next step was for someone to upload a new patch 13:33:41 And yes mordred: never sleeps!! :) 13:33:55 annegentle, it should really be something quick to finish today, need to make sure it fully complies with our infra team needs ;) 13:34:02 heh sleep when you're dead right koolhead17? :) 13:34:16 ladquin: excellent. And thanks mordred for the help 13:34:25 mordred, hey, thanks, yes, I need to amend that 13:34:30 ok ready to talk translation? 13:34:37 #topic Translation uploading/downloading scripts 13:34:48 hi, I'm here 13:34:50 Daisy: you have any news to report? 13:35:04 #link https://review.openstack.org/#/c/25810/ 13:35:06 the patch is submitted to git review. 13:35:09 I did see that ^^ 13:35:27 just need to discuss with you about how to store the translation po files. 13:35:36 I guess, there will be a big amout of po files. 13:35:45 Daisy: ok, sure. I saw .tx directories somewhere? 13:35:48 * annegentle looks 13:36:30 #link https://github.com/openstack/openstack-manuals/tree/master/doc/src/docbkx/openstack-install/locale 13:36:35 Do you think, if the authors/readers will be bothered if we put these files under master ? 13:36:37 Also locale directories 13:36:56 Daisy: honestly it's not bothering me lately but I have super mega fast Internts. 13:37:04 what do others think? 13:37:16 * annegentle wonders if translation also is a factor for the refactor 13:37:29 I have a slight personal preference for keeping the repo small in size, due to frequent travel = unreliable/slow internets 13:37:37 Nova/Keystone and others have the po and pot file in master, but I think, their size are small, not like documents. 13:37:40 but I wouldn't allow my personal preferences stand in the way :) 13:37:54 ah - if there's an established precedent, maybe we should follow it 13:37:57 fifieldt_: yeah compltely understand that 13:38:12 so we agree to put them in master? 13:38:16 sure 13:38:23 Daisy: mordred: what are some of our other options? Just to be sure. 13:38:24 ok. 13:38:38 slow internet reminds me of my broadband 13:38:39 use a different branch? 13:39:10 we put the po files in a different branch, like, translation. If the developers don't want to download translations, they can pull from master. 13:39:27 Actually, I have not clear ideas. 13:39:31 I'm not a git master. 13:39:32 Daisy: oh yeah that would make sense, actually, why not store with stable/folsom and also stable/grizzly in a month? 13:39:56 storing with stable makes sense to me 13:39:58 it changes less 13:40:06 = less frustration for translators ? 13:40:29 when I asked on the list, jaypipes said something about submodules? 13:40:29 the translation po files will be changed because the downloading job runs daily. Can we put them in stable? 13:40:36 which sounded AWFUL I have to admit :) 13:40:53 yeah I really like starting with stable 13:40:58 stable :D 13:41:08 the translation po files will be changed daily, so they are not stable. 13:41:26 what's the disadvantages if we create a new branch? 13:42:37 Daisy: hm. I don't know... really we just want to keep translators happy while not preventing new doc contributions from being a pain 13:42:49 * koolhead17 is going to spend few days to understand Git magic 13:42:49 exactly. 13:43:13 Daisy: how much do translators know about the git branch label though? Do they see that much? 13:43:24 Daisy: or is it just the Jenkins robots that need to use the branch? 13:43:35 Daisy: because the Jenkins robots won't care if it's called "stable/relname" 13:43:50 Daisy: people might think that's odd but it might not matter? 13:44:01 translators doesn't need to know about branch lable. Branch lable is not required by Jenkins robots too. 13:44:48 Daisy: ok then I think it's okay to go with stable 13:44:56 ok then. 13:45:03 go with stable. 13:45:05 * annegentle hopes my future self doesn't hate me for that :) 13:45:12 hmmm! 13:45:25 haha 13:45:26 I think it'll work the way we want it to 13:45:32 I'm sure by next meeting we will know whether it was correct 13:45:36 and if it wasn't we can change it 13:45:43 right? 13:46:04 I have a question... 13:46:06 yeah 13:46:09 sure go ahead 13:46:16 when will stable/grizzly be created? or it has been created? 13:46:39 Daisy: so that was our discussion today. We need packages released (depends on Ubuntu) and install docs tested (in progress). 13:46:41 * fifieldt_ is watching crazy tram track maintenance vehicles randomly block an intersection in very interesting ways 13:46:54 Daisy: my guess is either end of April or first 2 weeks of May 13:47:00 Daisy: will that be too much delay? 13:47:04 ok, so that might be a problem - we probably want grizzly translation to start sooner, yes? 13:47:12 fifieldt_: well, why translate what isn't done? 13:47:15 so I have to use stable/folsom to store the translation of grizzly? 13:47:18 fifieldt_: is my thinking? 13:47:24 Daisy: oh. No. :) 13:47:29 Daisy: Hm. 13:47:42 So, here's the release process for docs: 13:47:59 #link https://wiki.openstack.org/wiki/Documentation/Release 13:48:03 that takes at least a day 13:48:12 I could do it this week? 13:48:16 I could do it the week after Summit 13:48:25 Or could wait for Install docs to be done. 13:48:37 Or. 13:48:38 I'd say after summit and when install docs are done? 13:49:00 writerDiane: that's my preference but hadn't considered translations 13:49:17 Daisy: my top priortiy would be the Operations Guide anyway, which is in stable/folsom 13:49:22 and is very folsom 13:49:50 there is a operation guide in master , isn't it? 13:49:58 can't translation be staged? I.e. make a prioritized list and work through it? install guide would be last? 13:49:58 indeed 13:50:00 Daisy: yep it matches folsom 13:50:12 writerDiane: yeah that makes sense 13:50:23 Daisy: do you have a sense of whether translators work thorugh a list? 13:50:40 when we have coordinators, we can ask the help from coordinators. 13:50:46 Daisy: yeah 13:51:21 Daisy: so I'd like a decision on stable/folsom and stable/grizzly -- is it okay if stable/grizzly is in a few weeks? Like after the Summit? 13:51:41 so you mean that the translators start translation of stable/folsom? 13:52:11 Daisy: the translators wait until after the Summit and work on stable/grizzly 13:52:13 I need to think it more. 13:52:31 Daisy: except for the Ops Guide, start on that in stable/folsom 13:52:39 currently, translators are doing the translation of master, that means, the latest version, the version are being developed. 13:53:03 Daisy: ok let's think about this from a release perspective. Translators won't wait for a release, they work on master. 13:53:10 Daisy: so how do we "release" master docs? 13:53:39 translations will be later than the release of master. 13:53:51 * ladquin wonders if Transifex works with translation memories 13:53:54 But if we keep translators to translate the old version of documents, will they be happy? 13:54:04 ladquin: yep, it does! One of the reasons we picked it 13:54:05 Transifex can work with translation memories. 13:54:15 Daisy: for the Ops Guide, for sure it's best. 13:54:35 Daisy: for other guides, master would be ok, as long as we know what happens at release time 13:54:37 ok. I need to think more about it. Maybe we won't make decision tonight. 13:54:56 Daisy: I think that we might end up making smaller docs repos after the refactor? Possibly? We already split out ops/admin guides from API 13:55:04 I'm not able to handle the documents differently. 13:55:33 Would putting docs in individual repositories matter? 13:56:41 The review Daisy posted is the script that links to Transifex and back 13:56:45 That's the only way to take care of the tradeoff of size, is to put items into smaller "buckets" 13:56:52 My guess is that it can be modified for any scenario 13:56:59 fifieldt_: yep probably so 13:57:04 currently, the docs are in a single repository. So I look at them as single repository. When a single document is updated, the update event will triger the uploading jobs, the updated POT file will be upload to Transifex. 13:57:12 fifieldt_: what do you think of smaller repositories? 13:57:21 I prefer the big repo 13:57:43 fifieldt_: okay 13:57:44 I do a lot of grepping to find stuff across different docs 13:57:52 fifieldt_: yep 13:58:01 Daisy: I think it's okay to use master 13:58:10 Daisy: I don't think the pot files will be all that big 13:58:19 there are only two Jenkins jobs for me: uploading and downloading, a single repository. Not several jobs for individual documents. 13:58:26 Daisy: yeah 13:58:43 so we use master firstly. 13:58:59 Daisy: yep. I still want to understand what happens when we cut stable/grizzly in a few weeks? 13:59:00 And then we discuss more in the summit. 13:59:27 Daisy: yep 13:59:30 versioning will be a problem for translation too. 13:59:31 Daisy: are you able to come? 13:59:36 I should list this as a topic. 13:59:37 Daisy: yes it will :) 13:59:41 Yes, I'm able to come. 13:59:46 yayy! 14:00:10 Daisy: wonderful! 14:00:16 Okay, great! 14:00:16 :) 14:00:22 Wow where did the time go? 14:00:28 we are run out of time. 14:00:34 #topic Open discussion 14:00:50 or I can end the meeting if no one has anything :) 14:00:55 * fifieldt_ needs tex mex 14:00:58 hee 14:01:12 Good tortilla chips and salsa just don't travel well 14:01:14 annegentle: what did I do? 14:01:20 mordred: all of the things! 14:01:24 awesome! 14:01:27 :P 14:01:29 hahah 14:01:42 mordred: if your team can attend the Docs Translation session at the Summit next week on Monday it would be super-uper helpful 14:01:53 annegentle: yes. that one is definitely on my list 14:02:09 I'll make olaph be there for sure, but I believe more of us will be there as well 14:02:11 #info Monday 2013-04-15 13:50 - Translation management enhancement 14:02:13 annegentle: am working on that install doc with nova-network 14:02:25 ttx: it would be GREAT if I could get an ical feed from sched.org 14:02:26 all hail nova-network 14:02:30 i will not add/push it in offical repo unless i test it atleast 10 times 14:02:31 :) 14:02:31 koolhead17: ok, how can you incorporate? 14:02:50 fifieldt_: i don`t want nova-network die so soon 14:02:51 :D 14:02:52 koolhead17: oh well propose apatch and we'll see how you incorporate :) 14:03:03 koolhead17: yeah it's definitely not dead since quantum is so hard 14:03:09 mordred: if only sched was open source ;) 14:03:16 heh 14:03:24 ok, I'll end our meeting -- thanks all for attending! 14:03:27 #endmeeting