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