13:00:53 #startmeeting DocTeamMeeting 13:00:54 Meeting started Tue Sep 24 13:00:53 2013 UTC and is due to finish in 60 minutes. The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot. 13:00:55 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 13:00:57 The meeting name has been set to 'docteammeeting' 13:01:00 o/ 13:01:05 I think I spell it differently each time, sigh. 13:01:16 \o/ 13:01:18 Ok, Agenda is at https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting 13:01:47 #topic Action items review 13:01:50 #link http://eavesdrop.openstack.org/meetings/docteammeeting/2013/docteammeeting.2013-08-28-13.01.html 13:01:59 Let's see. I clarified our reviewing policy 13:02:13 let me find the link for archiving/notes 13:02:57 #link https://wiki.openstack.org/wiki/Documentation/HowTo#Reviewing_Documentation 13:03:11 That was all the action items. 13:03:24 #topic Admin guides 13:03:33 Just bringing up admin guides so we all have the status 13:03:44 hello all 13:03:51 Nermina (who will be here soon) completed the patch to move the Networking Admin guide 13:03:55 Oh hi nermina! 13:03:56 :) 13:04:05 hey :) 13:04:17 Move the Networking Admin guide content into all the other places (install, config, admin) 13:04:26 Thank you nermina! That was a pile of work 13:04:35 no problem! 13:04:46 yw 13:05:03 o/ 13:05:04 Any other reports on admin guides? I also did a redirect from /trunk/openstack-compute/admin 13:05:06 So, shall we remove the networking guide from publishing and docs.o.o? 13:05:07 radsy: go 13:05:11 AJaeger: yes 13:05:14 yes 13:05:24 annashen, give me that action item 13:05:44 #action AJaeger to remove Networking Admin Guide builds and links 13:05:44 I meant annegentle instead of annashen ;( 13:05:51 AJaeger: yeah that happens more often than not! :) 13:06:02 still need to consolidate advanced features tho Diane has confirmed that the current version is fresher 13:06:14 radsy: oh sorry did you have a question or were you just waving? :) 13:06:21 just waving:) 13:06:24 nermina: yep okay 13:06:39 radsy: o/ <--- I'll wave back then! :) 13:07:02 nermina: ok, what's a time estimate for consolidating the advanced sections? 13:07:07 it could go away today, i just need to confirm the state 13:07:36 nermina: ok great 13:08:09 Okay any more Qs on admin guides? There are just two with "admin" in the title - the Cloud Administration Guide and the Admin User Guide 13:08:39 i think the distinction in terms of content is fairly clear 13:08:41 Thanks for all the hard work on the consolidation - nermina, dianefleming, AJaeger 13:08:50 sure 13:08:53 sgordon: yeah I like how it shaped up 13:09:03 Oh, i have a comment - 13:09:08 thank you annegentle 13:09:10 dianefleming: sure 13:09:51 I think the Cloud Administration Guide is titled "Cloud Administrators Guide," but it should be "Cloud Administrator Guide" (IMO) - so it mimics the "User Guide" and "Admin User Guide" (singular audience User, Administrator, etc.) 13:10:20 dianefleming: ok, I agree, nermina, sgordon, AJaeger, what do you all think? 13:10:34 dianefleming: i noticed the discrepancy too and could fix it when i put in compute and dashboard edits from smes 13:10:41 cool! 13:10:48 the book is called "OpenStack Cloud Administration Guide" 13:10:56 oh! 13:11:04 http://docs.openstack.org/admin-guide-cloud/content/ 13:11:29 but yes, /trunk/index.html says differently. 13:11:35 Let'S agree on one name 13:11:52 just need your votes, annegentle, dianefleming, ajaeger, sgordon, and all 13:11:56 :) 13:12:01 Administrator 13:12:03 nermina, i dont have a strong opinion on this one 13:12:05 (shocking i know) 13:12:07 :) 13:12:10 :) 13:12:22 I agree with dianefleming for consistency of the titles - Administrator 13:12:30 +1 Administrator 13:12:52 +1 administrator 13:13:14 +1 administrator 13:13:40 thanks emilienm 13:14:32 all, sounds like administrator it is 13:14:38 * NickChase disagrees but he was late and didn't hear the arguments so he'll be quiet. :) 13:14:43 lol 13:14:50 hee 13:14:52 ahah 13:14:55 NickChase: go ahead ! 13:15:02 #agree Cloud Administrator Guide title change 13:15:04 there were no arguments 13:15:08 dianefleming: can you do the patch? 13:15:11 sure! 13:15:18 #action dianefleming to patch Cloud Administrator Guide for new title 13:15:23 dianefleming, I'm patching index.html already 13:15:25 Ok, on to install guide(s)? 13:15:26 It's ok, I'm not that intense on it. 13:15:33 #topic Install guides 13:15:47 Doh, no shaunm this morning. 13:16:06 I've been asking him to patch what he's got, but it sounds like it's such a major rewrite he's struggling with a single patch 13:16:19 I'll keep asking today for him to see how we can split up the work 13:16:22 my concern with that is that we're less than a month out 13:16:28 sgordon: oh yes me too 13:16:31 and it's very hard for anybody else to contribute 13:16:34 if there is no base :) 13:16:35 sgordon: what can we do? 13:16:45 i think he just needs to commit what he has 13:16:51 is there any way someone else can help him? 13:16:54 "commit early and often" 13:16:55 agreed 13:16:59 sgordon: yeah I agree 13:17:01 +1 13:17:08 i'd be happy to help 13:17:13 nermina: great. 13:17:17 And I'm willing too 13:17:24 one idea is that we could each take an architecture 13:17:32 I could take the Obj. Storage + Identity 13:17:35 for example 13:18:11 Ok let's talk to Shaun today 13:18:22 ok 13:18:25 #action annegentle discuss Install patches with Shaun 13:18:45 #topic Standards for reviews 13:19:00 This came up in a review where Diane had done a lot of copyediting/cleanup. 13:19:06 And I wanted to discuss here 13:19:32 yes 13:19:44 I agree with sgordon here. 13:19:48 tom's not here to talk about his position 13:19:51 I would like to add more openSUSE information 13:20:19 AJaeger: yeah and you feel like the install's "blocked" right? 13:20:20 everyone seems okay with establishing writing standards, but there was controversy about whether we should standardize on a specific version of english (en-US, en-AU, etc.) 13:20:26 AJaeger: I'm in total agreement 13:20:38 dianefleming: thanks was trying to summarize and that's a good summary 13:20:39 annegentle, yes, I feel blocked 13:21:15 can you provide some detail? 13:21:33 the suggestion was that we standardize on en-US 13:21:45 nermina: Sure, basically, we should all write to the conventions, but then the question was, what about comma placement, spelling, for regional differences? 13:21:46 tom and my position was that this wouldn't resolve many of the issues noted 13:21:50 which impact any dialect 13:22:01 yep sgordon 13:22:09 what kind of issues? 13:22:10 (and are also already conventions in many cases, but not always followed) 13:22:17 tense, latinisms 13:22:17 Correct - that wouldn't resolve other issues, but I think it doesn't look good to have a single book written in several dialects 13:22:17 Sorry, I need to leave for a meeting - I'll try to be back as soon as possible 13:22:57 hmm, i think the simpler the better 13:22:58 the actual example was whether to put commas inside or outside quotation marks 13:22:59 #link https://review.openstack.org/#/c/46811/ 13:23:15 and I don't see the harm on standardizing on en-US - but perhaps I'm missing something 13:23:16 but that was ultimately resolved with markup of the values i think (instead of quotations) 13:23:22 that and spelling differences 13:23:26 most of the world puts them outside 13:23:28 I think that it would be good to standardize -- at a lower priority than actual content 13:23:30 My thinking is we need to ensure reviewers and writers know we write to conventions. 13:23:42 But yes, the priority is what trips people up. 13:24:07 basically I think that spelling "colorise" with an "s" shouldn't block a merge. 13:24:10 I don't think we're (yet) prioritizing copying editing over content creation. 13:24:14 i just want to establish what our standards are, versus cleaning up the books to meet those standards - it's more about future contributions. if people know what's expected, they can meet the standards 13:24:16 my contention is that many of these things are already part of the standards we are supposed to be following 13:24:17 if someone has time to go back and fix it, great. 13:24:24 NickChase: heh you're in Tom's and Steve's camp. 13:24:28 so i dont see how adding en-US as a standard will change those issues getting through 13:24:37 Only because I've been in their shoes, in reverse. 13:24:50 NickChase: which shoes? the editor's? 13:24:56 The writer's. 13:25:01 I write for English pubs 13:25:14 it won't change those issues getting through 13:25:15 and I sometimes get dinged for "Americanisms" 13:25:23 but it will give people guidelines 13:25:34 that's my point; as long as it doesn't block a change, I'm for standardization. 13:25:39 if someone has time to fix it, great. 13:25:47 so if someone provides edits on a review, they can justify their suggestions 13:25:50 as i said though, they already have guidelines on most of the issues you noted in that email because they are non-dialect dependent 13:25:59 NickChase: I think we might as well review to a standard and patch it before it gets into the repo if needed 13:26:11 dianefleming: right that's my thinking as well 13:26:11 @nickchase I agree 13:26:36 We need to be able to point to a standard, our Conventions page could just say "we review for en-US" and that would be enough I think. 13:26:53 @annegentle if you're saying it's a target, then I agree. If you're saying it's hard-and-fast-must-be-followed-or-else rule, then I disagree. :) 13:26:55 Worth a try anyway, I do defer to sgordon on this though if you see more mish-mash 13:27:06 NickChase: eh, I'm never a hard-and-fast :) 13:27:26 AnneGentle: Then I agree. :) 13:27:29 NickChase: but I do feel a need to set a bar, we've done a ton of cleanup, let's not degrade. 13:27:47 it's unfair to have it to en-us but then you have to have some kind of standard 13:27:48 it can't be hard and fast because this gate is a human gate! it's not automated 13:27:53 Tom also said that he doesn't think translators need it, does anyone else have an opinion about affect on translators? 13:28:22 i think the impact of en-US versus en-XX is minimal for translators 13:28:23 ("it" being en-us or en-gb) 13:28:32 obviously tense, voice etc. do have an impact 13:28:44 but as we stated that's not really down to the particular dialect used 13:28:46 I don't think they need it either 13:28:52 sgordon: okay, yeah I'm sure colloquial speech is tougher than ize or ise 13:28:56 yup 13:29:11 annegentle: depends if the translator is en-gb. they may be more set in their writing/editing ways 13:29:26 Ok, anyone want to propose what we can agree on for standards? My 2 drafts would be: 13:29:52 1. Standardize on our /Conventions/ page and add en-us, review to those standards, patch as needed. 13:29:53 or 13:30:23 hm. It's the or I'm not sure of. sgordon what would be the alternative? 13:30:55 i dont know that it's necessarily an or 13:31:02 sgordon: okay 13:31:04 i think regardless of whether standardizing on dialect or not 13:31:07 I think you need to just add "if feasible" to the end and you're good 13:31:19 NickChase: seems fair enough. dianefleming what do you think? 13:31:24 because you don't want people who aren't confident in their own brand of en-US to feel like they can't review 13:31:30 there needs to be *some* focus in the review pipeline on the issues noted in the conventions 13:31:32 that sounds fine - 13:31:39 it feels never feasible against an install guide that's not done, but sigh. 13:31:44 which i would argue currently there is not to a degree 13:31:47 i don't want to discourage contributors in any way! 13:31:48 lol 13:31:50 sgordon: yes 13:32:06 Ok I'm just going to add the Conventions to the reviewers guidelines 13:32:17 i'm just a nit picker and it drives me nuts to see a word spelled differently in a single paragraph....:) 13:32:21 #action annegentle to add Conventions to the reviewers guidelines 13:32:24 which i have seen! 13:32:27 dianefleming: yes and it's why you're a damn good writer 13:32:33 ha! 13:33:01 I left translation status on the agenda but I don't know of any 13:33:05 #topic Translation status 13:33:11 I dont' know of any updates or news, anyone else? 13:33:27 negative, i havent heard anything 13:33:31 Ok moving on 13:33:40 #topic Doc tools update 13:33:44 * sgordon makes a note he probably should be attending their meetings too 13:34:03 sgordon: yeah theirs are in my evening so I haven't made it to a single one yet. 13:34:19 sgordon: but it would be great if you can try to get to some 13:34:43 Ok, we do have 1.10.0 Maven plugin available. dianefleming and I are doing a test blitz of all outputs Friday 13:34:58 I will pick what we should standardize on for the release once we get some testing done 13:35:15 1.10.0 has some issues for the API reference page 13:35:18 is there any intent to use the olink functionality for this release at this point? 13:35:22 yes, i plan to write a test plan before the testing 13:35:30 sgordon: no not for havana 13:35:32 dianefleming: awesome 13:35:35 ok cool 13:36:08 oh and do look at the new doc bug functionality David's adding 13:36:25 pretty cool that 13:36:42 #link http://lists.openstack.org/pipermail/openstack-docs/2013-September/002855.html 13:36:50 shaunm is here. hi shaunm! 13:36:56 what do you all think about having an "lp" icon for logging a bug? 13:37:03 hi nermina 13:37:13 shaunm: hey -- let's switch to install guide 13:37:18 my only concern would be whether all readers necessarily will recognize that 13:37:28 but given they have to have an lp account to successfully log a bug anyway 13:37:32 im not sure that is an issue 13:37:33 sgordon: yeah good point, and we may be switching off of LP someday 13:37:39 an icon instead of text? 13:37:40 annegentle: bug icon! 13:37:47 nermina: I thought of that too! 13:37:53 yeah a more generic bug icon with appropriate alt text 13:37:55 might be better 13:37:56 shaunm: to match the PDF and RSS icons in the grey bar 13:38:12 shaunm: moves it to the top (for visibility) 13:38:28 love this functionality! brilliant! 13:38:42 sgordon: is yours text only, and placed at the bottom of the page? 13:38:46 yeah 13:38:53 at the end of each
13:38:56 sgordon: okay I was trying to find a link yesterday 13:39:01 so depending on chunking may be more than one time a page 13:39:09 sgordon: oh huh. Hm. 13:39:12 I suspect text-only at the bottom of the page would get noticed more than an icon in the header bar. I could be wrong. I'm often wrong. 13:39:14 it's a long story but it's in some but not all of our guides atm 13:39:35 shaunm: yeah David's thinking was to keep it near Disqus comments. 13:39:43 shaunm: but then Sam had another idea 13:39:52 Do we need the Disqus comments? 13:40:05 dianefleming: Ideally we'll move to the ask.openstack.org threads instead! 13:40:20 Couldn't we just put a link to that and get rid of disqus? 13:40:28 dianefleming: but I don't have someone to do that design/integration 13:40:36 dianefleming: that's not a bad idea, what do you all think? 13:41:03 dianefleming: some people are solving problems in the comments, but it still usually comes back to a doc bug 13:41:45 i think dropping the disqus might be appropriate 13:41:47 yeah, if it's a doc bug (or a dev bug), it should be a bug. for general questions, ask.openstack.org should be good - but i don't know 13:41:55 potentially as well as report a bug you could add a link to ask.openstack.org 13:42:00 I wonder if we could link to ask.openstack.org 13:42:03 sgordon: heh. 13:42:10 and then do real integration later 13:42:18 embedding ask.openstack.org directly in the page (like disqus is now) will be more time consuming 13:42:25 sgordon: yep 13:42:28 annegentle: if the link to ask also scooped in the section name or otherwise reduced the amount of typing 13:42:29 but for now a link might do the trick 13:42:41 nermina: oh yeah true 13:42:53 I'm for the link; I'm for anything that increases Ask's traffic. 13:43:00 that is effectively what it does for the bug link 13:43:06 so i am sure the same can be done for ask 13:43:11 (pre-populate the title) 13:43:15 cool 13:43:18 NickChase: sgordon: yep I bet so. 13:43:32 Not sure prepopulating the title is good, though 13:43:33 anyone want to investigate further? 13:43:44 because then we wind up with people not thinking about what the title should actually be 13:43:45 NickChase: I wouldn't want a flood on ask 13:43:52 no, no, not a flood, of course. 13:43:57 NickChase: right and it would not be 'a question" 13:44:07 annegentle: exactly 13:44:24 I think it's worth further investigation. I have Todd Morey working on a new design, and I think part of my reqeust was ask integration. 13:44:27 I'll follow up with Todd. 13:44:34 if we leave the title unpopulated it forces people to think about whether this is really appropriate for ask. 13:44:38 NickChase: true 13:44:51 Ok let's circle back to install guide 13:44:58 #topic Install guide status 13:45:22 shaunm: What can we do to help? What can you do to push us pieces? 13:46:06 shaunm: we're all feeling a bit blocked 13:46:13 annegentle: did you get a chance to look over the diff I sent yesterday? 13:46:26 shaunm: hm, how'd you send it? 13:46:32 email, as a git diff 13:46:42 shaunm: ok found it 13:47:20 shaunm: oh ok, I think you could patch with this diff -- it's commented 13:47:50 to review.openstack.org? 13:48:22 shaunm: yeah, then let's figure out how to parcel out the work 13:48:56 right, so it's hard for others to build on it before it's actually pushed 13:48:58 shaunm: it's just way too late in the game 13:49:06 shaunm: right 13:49:23 and I'm not at all comfortable pushing something like that to master. I'd normally use a development branch for this kind of thing 13:49:40 shaunm: but for us, our master is where we keep working 13:50:13 all right 13:50:37 shaunm: and we dont' have a way to start a sandbox branch that I know of, not with our infrastructure 13:51:40 I think at this point people will understand if things are a bit wonky. besides, if the current guide were sufficient, you wouldn't be rewriting it. 13:51:44 shaunm: only other idea I have is to publish only to docs-draft? 13:52:04 Overview and Architecture, Basic Operating System Configuration, Nova Compute 13:52:05 Services, and Compute Node chapters 13:52:10 so are these done ^^ 13:52:33 I have to head out for an appointment - bye all 13:52:40 dianefleming: okie doke 13:52:46 yeah i have to duck in a few minutes too 13:52:55 shaunm: yes we do understand this is a tough task, but we need to be unblocked 13:53:01 bye dianefleming 13:53:06 see ya later dianefleming 13:53:13 shaunm: and no one will fault you!! This is tough content to write, test and organize. 13:53:31 +1 annegentle 13:53:45 shaunm: so let people help you 13:53:47 I have the content for all of those. I just have to put it in docbook and make it read well 13:54:08 shaunm: If you want I can put it in docbook for you 13:54:09 shaunm: maybe your patch can include the non-docbook notes? 13:54:19 NickChase: that would be awesome 13:54:30 docbook I can do in my sleep. 13:54:40 shaunm: glad to help as well 13:54:46 docbook isn't a problem for me 13:54:47 heh 13:54:50 true that nickchase 13:55:01 shaunm: but it's a matter of time; this is something I can do to help you 13:55:13 so you can concentrate on content 13:55:53 shaunm: basically just keep patching, I'd expect 2x a week from here on 13:56:01 ok 13:56:06 shaunm: Once it's in docbook it'll be easier for you to just do the readability 13:56:07 shaunm: take NickChase up on his offer :) 13:56:34 yeah 13:56:40 shaunm: is your non-docbook text all your testing? 13:56:40 I promise not to judge. :) 13:56:44 i think we all recognize you are performing open heart surgery 13:56:48 it's really no faster for me to write without markup than with 13:56:55 so we wont be too brutal on the in progress reviews 13:56:55 +1 sgordon 13:57:03 +1 sgordon 13:57:23 shaunm: yes just let us review (non judgementally) :) 13:57:37 Ok 13:57:39 onward! 13:57:47 #topic Bug report, DocImpact state 13:57:49 Quickly, 13:58:00 #link https://bugs.launchpad.net/openstack-manuals/+milestone/havana 13:58:11 hold on a sec, i have a q, annegentle 13:58:57 will the new content obsolete the old install guide? 13:59:15 or absorb it 13:59:19 Our confirmed is fewer than Fix Released \o/ 13:59:38 shaunm: what's your thinking? obsolete or absorb? 14:00:02 we have people editing networking there 14:00:04 it will be the one true install guide. it happens to reuse some content from the existing install guide. 14:00:17 nermina: ok, sounds like that's safe to do 14:00:31 more absorb than obsolete 14:00:38 mostly reuses conceptual info. tasks are almost all rewritten 14:00:45 cool 14:01:24 sorry to interrupt, bugs! 14:01:30 nermina: no worries! 14:01:44 Really we're in good shape, better than past releases, but there are a ton of "medium" bugs 14:02:00 And only about five in progress 14:02:04 so keep picking up bugs if you can 14:02:17 i'll be able to take on more between cloud admin edits 14:02:22 I also did a walkthrough of DocImpact 14:02:24 #link http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/ 14:02:47 and would love input on whether that's how these DocImpact ones typically work -- would that set of questions help people work on DocImpact bugs more efficiently? 14:02:58 Ok, that's our hour... sorry didn't leave any time for open discussion! 14:03:10 Want to continue open discussion in #openstack-doc? 14:03:34 ok with me 14:03:37 Ok, I'll be in openstack-doc, thanks all for joining! 14:03:41 #endmeeting