13:02:00 #startmeeting docwebteam 13:02:01 Meeting started Tue May 14 13:02:00 2013 UTC. The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot. 13:02:02 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 13:02:03 * nickchase raises hand 13:02:05 The meeting name has been set to 'docwebteam' 13:02:11 writer___: hee hee. Fill in the blank? 13:02:14 morning / evening /afternoon all 13:02:18 * sld raises hand. 13:02:20 hey nickchase welcome! 13:02:35 hi sld (short nick) 13:02:42 Thanks anne 13:02:52 Okay, the agenda is at https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting 13:03:10 #topic Previous action items 13:03:25 last meeting's notes are at http://eavesdrop.openstack.org/meetings/docwebteam/2013/docwebteam.2013-04-09-13.00.html 13:03:37 I had an action to add more info about 1.7.2 to the HowTo wiki page 13:03:59 Aren't we at 1.8.0 now? 13:04:05 I added info about the Maven plugin, but we're already at 1.8.0 so I don't think I should document a specific version 13:04:11 dianefleming: yup 13:04:15 agreed 13:04:33 So, I added a section about the Maven plugin and edited a section and PDF, and so on. 13:04:35 doesn't david c keep release notes for each version? could we link to that? 13:04:37 were all poms migrated? 13:04:41 And fixed a link to the release notes 13:04:41 yep 13:04:54 ladquin: yes, to 1.7.2, now we should move to 1.8.0 13:05:05 oh, ok, good 13:05:06 ladquin: though 1.8.0 is not as critical 13:05:23 The only other ACTION was to release Grizzly docs. DONE and Done and done. 13:05:25 whew. 13:05:33 #topic Grizzly release 13:05:35 HURRAY! 13:05:57 Does anyone have any input/feedback/gripes about the Grizzly release (docs specifically?) 13:06:10 how did the DocImpact work for you? etc. 13:06:38 I have some problems with inconsistencies in some areas (config and cli options, etc.), but that is already being worked on, as you know. 13:07:13 I have some confusion about what to do with DocImpact bugs - 13:07:15 sld: always need more consistency work 13:07:18 dianefleming: sure 13:07:19 do we have an official process? 13:07:42 dianefleming: yep, here: https://wiki.openstack.org/wiki/Documentation/HowTo#Using_the_DocImpact_Flag_in_a_Commit_Message 13:08:38 I thought grizzly was a bear of a release. Ha. Kidding. 13:08:48 Is there a way we could automate the creation of doc bugs from dev bugs? Once someone flags a bug as DocImpact, could a doc bug be autogenerated? 13:08:52 that would save a step 13:08:57 lol annegentle 13:09:08 dianefleming: man that would be great. I bet the Launchpad API has something? 13:09:09 hahah :P 13:09:28 yeah, because the current process is extra work - 13:09:35 dianefleming: yeah it's very manual 13:09:44 dianefleming: and Tom (fifieldt) does it all more or less 13:10:06 I can look at the doc bug autogeneration with tom... ;-) 13:10:15 I'll take an action item to ask ttx or the -infra team if they have ideas 13:10:17 awesome! 13:10:21 sld: that would be great too! 13:10:49 #action: annegentle to ask ttx and -infra folks about DocImpact automation 13:10:56 There is definitely an API to create a bug, so hopefully they should be able to do that. 13:10:57 another issue I have is, once a new release is cut, I am not sure which bugs should be backported to earlier release 13:10:58 It would also be nice to stop cluttering up our mailing list with DocImpact 13:11:20 +1 to that 13:11:24 dianefleming: right now, nearly all patches should be backported because nothing affects "only havanah" right now 13:11:45 dianefleming: at least, not that I've seen yet. 13:11:47 is there a way to have a bug target more than one release? 13:12:03 well, some docs aren't release-specific - how do we handle those? 13:12:15 dianefleming: not that I know of, it means 2 patches in a single bug. The "Fix Released" automation doesn't care what branch a patch is on 13:12:18 or the doc spans a few releases 13:12:49 i guess what i'm saying is, is there a way to indicate in the bug that it applies to multiple releases? so that we know to backport it? 13:12:52 dianefleming: ok, then I suppose I mostly care about ones that are asked on the comments 13:13:07 ok 13:13:11 dianefleming: no, not that I know of... we used review comments to request backports previously 13:13:17 dianefleming: and it's a judgement call 13:13:27 dianefleming: might be able to do that where you click on "also affects distribution" or "also affects project" on the bug page itself. 13:13:44 okay - 13:14:10 okay, I'll move along 13:14:25 #topic Doc titles consistency work 13:14:51 dianefleming has a series of patches to get consistency in the titles across the docs 13:14:57 this has been a huge job 13:15:04 well, huge, er, tedious? 13:15:13 ha - a little of both 13:15:26 it took awhile to figure a few things out - the actual work is just tedious 13:15:32 but i'm almost done 13:15:52 yeah. The bugs have the title changes, such as https://bugs.launchpad.net/openstack-manuals/+bug/1178388 13:15:54 Launchpad bug 1178388 in openstack-manuals "openstack-manuals - update book titles for consistency: DEVELOPER GUIDES (specs)" [Medium,Fix released] 13:16:08 #info Titles changing for consistency, review the patches 13:16:12 #link https://bugs.launchpad.net/openstack-manuals/+bug/1178388 13:16:42 yes, that bug links to a bunch of changes - each one needs to be reviewed separately, since they are all in different projects 13:16:50 #link https://review.openstack.org/#/dashboard/2448 13:17:07 yeah I think that link ^^ shows a lot of them together 13:17:17 any questions on the title consistencies? 13:17:53 honestly the install guides were the toughest, https://bugs.launchpad.net/openstack-manuals/+bug/1177075 13:17:55 Launchpad bug 1177075 in openstack-manuals "openstack-manuals - update book titles for consistency: INSTALLATION GUIDES" [Medium,Fix released] 13:18:11 I'm still working on a patch that makes basic and advanced more clear 13:18:32 though install needs the deepest detanglement 13:18:37 * koolhead17 joined late 13:18:39 yes - 13:18:45 hey koolhead17 13:18:48 I can possibly help with the install docs, since I do a lot of that. ;-) 13:19:05 sld: that would be awesome. I have a call this week with Cisco writers as well to help out 13:19:09 sld, would love to see you 13:19:15 hey annashen 13:19:19 annegentle, 13:19:20 sld: it's tough to know how to coordinate, honestly, but we have to try' 13:19:35 sld: let's meet this week, k? 13:19:45 #action annegentle to set up meeting with sld to talk about install docs 13:19:46 sounds good. 13:19:56 #topic API site navigation and versions 13:20:19 Great feedback on the new navigation for the API reference page -- and the version numbers are helpful too. 13:20:27 Nice work!! 13:20:32 cool! 13:20:44 navigation is awesome 13:20:49 dianefleming rocked it 13:21:00 thanks!! and thanks to david cramer 13:21:08 #info API reference page has version numbers and navigation 13:21:16 #link http://api.openstack.org/api-ref.html 13:21:29 yes, thanks to dwramer too 13:21:42 er. He's usually dwcramer? Anywho. 13:21:51 yes :) 13:21:51 awesome page... GJ....just bookmarked it. 13:21:55 The mailing list feedback was positive and Gabriel Hurley likes it. 13:22:06 gabriel has good taste 13:22:12 ha 13:22:29 dianefleming also uncovered a bug with the way the api-specs.html page was getting overwritten. 13:22:30 :) 13:22:48 Okay, on to configuration reference info! Reference info abounds. 13:22:52 #topic Auto-generated configuration reference tables 13:23:18 There are several patches with newly-created configuration tables such as https://review.openstack.org/#/c/28903/ 13:23:31 Basically sld and Tom have been busy automators! 13:23:46 Chime in on the mailing list (or here is fine too) if you have questions or input 13:23:59 I still want a walkthrough on where the strings come from so that I can patch the help strings. 13:24:11 Tom said he can do that, or maybe sld you and I can walk through it when we meet 13:24:22 yep 13:24:36 The mappings (groupings) are set with https://github.com/fifieldt/autogenerate-config-docs/tree/master/flagmappings 13:24:46 That's what gives you each table 13:25:10 After we have a good sense that the tables are complete, we'll incorporate them into references 13:25:11 well, those are partly done manually still, but a good part of it is automated... 13:25:29 sld: yeah, the .flagmappings are maintained by hand 13:25:45 one thing I wondered was, should the auto-gen code live in Oslo? 13:25:53 is it worthwhile to ask Mark if that's a good location for it? 13:26:00 or, does it belong in the docs repo 13:26:06 openstack-manuals/tools 13:26:28 i'm thinking the docs repo would be better ... at least when it is done.. since the goal is to update documentation with it. 13:26:33 #info Automated configuration information will be pulled from each project 13:26:43 sld: yep, makes sense then 13:27:00 Another thought is that we'll have to ensure translations can get picked up as well 13:27:18 for example, I saw that glance has .po files with the help text in them already 13:27:35 interesting. 13:27:38 (descriptions only would be candidate for translation, of course) 13:27:59 yeah 13:28:03 I'll post to the mailing list with any other thoughts I come up with 13:28:06 k 13:28:22 which naturally leads to the next topic... 13:28:28 # Restructure of docs 13:28:34 #topic Restructure of docs 13:28:37 I mean :) 13:28:59 #link https://blueprints.launchpad.net/openstack-manuals/+spec/restructure-documentation 13:29:13 So we have a blueprint 13:29:15 #link https://wiki.openstack.org/wiki/Blueprint-restructure-documentation 13:29:36 and we have a few people working on parts of it that I wanted to let people know about. 13:29:58 1. dianefleming is working on User Guide, API Reference 13:30:24 and api specifications (formerly known as api dev guides) 13:30:34 2. sld and fifieldt are working on the definitive list of config options 13:30:39 dianefleming: yep 13:31:00 but that also points out, I don't think the spec for the blueprint covers everything, Tom put it together as a starting point, and we need many many more details 13:31:12 3. I'm meeting with a few people this week about install 13:31:26 i agree - i'd like to update it with some details - is that okay? or do I need to clear it with someone? 13:31:34 go for it. 13:31:37 i plan to do the same. 13:31:37 3. nickchase is doing a content analysis of the "Admin Manuals" 13:31:56 dianefleming: yes, go for it, let's make that wiki page the place for our notes 13:32:06 awesome - thx 13:32:09 er that should have been 4. for nickchase :) 13:32:23 :) 13:32:39 The Operations Guide is undergoing an O'Reilly review to hopefully publish through their channels, we're in the planning phase for that. 13:32:52 annashen, w00000t 13:32:57 And I spoke to an architect yesterday who would like to work on the architecture half of that document as well. 13:32:59 annegentle, w00t 13:33:07 awesome news 13:33:18 But - it does mean we can only link to content in the Operations Guide (not xi:include it) 13:33:37 koolhead17: early stages, don't tweet it, it's not a done deal. 13:33:54 It's not a secret either, just not fully baked. 13:34:15 annegentle, its just awesome!! :) 13:34:22 So, with all that knowledge, let's keep doing the What goes where? exercises to refactor! 13:34:50 I don't really have anyone who wants to wrangle the "Developing OpenStack" content, but that's okay. 13:35:03 what does that entail? 13:35:11 my priorities would be the install/config, user guide, etc. 13:35:27 "developing OpenStack" - that's the Python book, right? 13:35:44 sld: The "Developing OpenStack" content is all in RST in the separate project repos. Publishes to http://docs.openstack.org/developer/ 13:35:47 annegentle, are we writing OS bible? 13:35:50 but has no overarching organization 13:35:55 koolhead17: heh 13:36:20 dianefleming: I don't know if it'll ever be a "book" 13:36:56 yeah - i think it needs a good edit - 13:37:07 boy howdy, yeah it does 13:37:11 some of the code doesn't work - i can take that specific book on to test it 13:37:17 and edit it 13:37:30 it's a ton of files across a bunch of repos, but might be a good cleanup effort. 13:37:37 it is spring afterall, time for clean up :) 13:37:47 you can give me that developer stuff - 13:37:56 the python book and the RST stuff 13:37:59 I can consolidate it all.... 13:38:06 ok, n/m ... too late ;) 13:38:13 hee 13:38:22 I like it when two people want a task :) 13:38:44 the three of us could meet outside of this meeting to see what it would entaile 13:38:47 entail 13:38:49 ha haha - i guess i haven't had my coffee yet 13:39:01 though really, the devs like to keep it their own, ya know? I've done patches that don't get accepted, etc. 13:39:10 so I'd rather prioritize in "our" realm? 13:39:16 let's you and I talk about it and see how to proceed? 13:39:17 yeah 13:39:22 cool 13:39:28 yea = keep things in this area. 13:39:31 ok, any questions on refactor? 13:39:39 nope 13:39:44 * koolhead17 loves title "OpenStack Bible" 13:39:46 #topic open discussion 13:40:04 We didn't talk about translation this week but I think the work is still going on. 13:40:13 ay yi yi 13:40:18 and we have a Japanese translator asking good Qs on the list. 13:41:47 I'm going on a field trip to a local farm today so I'll be away for most of the "day" but back online later. 13:42:03 Third graders are fun. Need coffee. :) 13:42:06 quick comment about bug 1178343 13:42:08 Launchpad bug 1178343 in openstack-manuals "Folsom doc links are difficult to guess (and get to through link nav)" [High,Confirmed] https://launchpad.net/bugs/1178343 13:42:16 Sorry I didn't update this patch, but wanted to maybe take advantage of the meeting time to ask you: 13:42:24 ladquin: oh yeah 13:42:25 I agree with Lorin's comments on consistency, but also one reason I like this layout is because it makes it very visibly clear you're not browsing a trunk doc page, but.. maybe that's just me. 13:42:50 ladquin: oh I see. Yeah the visual difference makes you know "we're not in Kansas anymore" 13:42:53 If you all prefer the current layout, I'll amend the patch now 13:43:00 ha, exactly 13:43:18 ladquin: I was thinking that a long, comprehensive listing, also indicates you're on a "special" one off page? 13:44:25 ladquin: by the time you like all the admin guides and isntall guides it'll look different :) 13:44:42 ladquin: but I was just happy you patched it! 13:44:51 annegentle, like the one for trunk? (is it long?) 13:45:14 so... shall I just use the current layout? 13:45:23 ladquin: there isn't a page like this yet... with all folsom books linked from it 13:45:31 ladquin: so you'd basically take the /run/ and /install/ pages and concatenate them 13:45:39 ladquin: yeah I think so... 13:45:57 ok, will amend the patch and you can all review it 13:46:48 ladquin: thanks a bunch 13:46:55 np! 13:46:57 Ok, I need to scurry to get on the bus to the farm. :) 13:47:04 Thanks all for attending, and talk more soon! 13:47:09 #endmeeting