14:04:39 <annegentle> #startmeeting docteam
14:04:39 <openstack> Meeting started Wed Jul 23 14:04:39 2014 UTC and is due to finish in 60 minutes.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:04:41 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:04:41 <annegentle> hey!
14:04:44 <openstack> The meeting name has been set to 'docteam'
14:04:45 <annegentle> Agenda is here:
14:04:46 <nickchase> Hey, annegentle
14:04:47 <annegentle> #link https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting
14:05:00 <annegentle> Let's see, action items from last meeting. It has been a while.
14:05:02 <Sam-I-Am> i noticed the date wasnt updated on the wiki
14:05:24 <annegentle> we didn't have a meeting last two weeks ago
14:05:26 <annegentle> so we already reviewed
14:05:35 <Sam-I-Am> ah
14:05:39 <annegentle> #topic Action items from last meeting
14:05:41 <annegentle> #info none
14:06:03 <annegentle> well I'll check to see if there were any in apac
14:06:43 <annegentle> nope nothing
14:06:59 <annegentle> #topic Architecture and Design Guide progress
14:07:33 <annegentle> #info It's Alive! The Architecture Design Guide has been merged
14:07:35 <annegentle> #link http://docs.openstack.org/arch-design/content/
14:07:37 <Sam-I-Am> yay
14:07:47 <Sam-I-Am> still needs some docbook fixerations?
14:07:54 <annegentle> Lots to do still, like get the glossary items integrated into common, make sure some tables came over
14:07:59 <annegentle> Sam-I-Am: if you see something say something
14:08:08 <annegentle> Sam-I-Am: it won't build unless it's docbook
14:08:28 <annegentle> I'm working on uploading print-ready PDF to lulu.com so we can order printed copies
14:08:29 <Sam-I-Am> well, yeah. thinking more like things that just didnt port well.
14:08:32 <annegentle> for the curious, it is 178 pages
14:08:37 <annegentle> Sam-I-Am: that's what took last week
14:09:27 <annegentle> I'll make sure the tables are in before the lulu upload
14:09:36 <annegentle> anything else that needs work, log a doc bug
14:09:50 <annegentle> #info Congrats to the writers! They worked hard and it shows.
14:10:08 <annegentle> I'll send 2 printed copies to the authors
14:10:09 <Sam-I-Am> thats a lot of writing in a week
14:10:19 <annegentle> I'll ask for their mailing addresses separately
14:10:24 <Sam-I-Am> wish we could get that around the network guide
14:10:25 <nickchase> The scary thing is that the writing was only 2 days.
14:10:43 <Sam-I-Am> ha, nice.
14:10:45 <nickchase> the rest was editing and polishing.
14:10:55 <annegentle> also thanks to nickchase for help getting it building! And for proofing the cover
14:10:59 <nickchase> Maybe the next sprint should be on Networking, what do you think, Anne?
14:11:02 <annegentle> I should have the cover edits back today
14:11:03 <nickchase> YW.
14:11:09 <annegentle> nickchase: there's a swarm for networking
14:11:17 <Sam-I-Am> its a 1-day thing
14:11:18 <annegentle> nickchase: but I really really don't want another sprint this year
14:11:33 <annegentle> nickchase: and the facilitation costs went way up (like tripled) so I don't know if we'll get funding again for a while
14:11:37 <nickchase> wow
14:11:53 <nickchase> might have had something to do with Adam bringing 2 people instead of 1
14:11:56 <annegentle> nickchase: so yes let's not have another sprint until at least fall 2015 and even then it should be on content we already have :)
14:11:58 <nickchase> he was training Faith.
14:11:59 <annegentle> nickchase: well
14:12:06 <regXboi> moo
14:12:12 <annegentle> nickchase: yes I'm aware of that :)
14:12:15 <nickchase> Yah know, I wonder if we could do one ourselves.
14:12:27 <nickchase> I mean, it's not rocket science.
14:12:39 <regXboi> when is the networking swarm aimed at?
14:12:41 <nickchase> not this year, I know
14:12:47 <nickchase> Just thinking out loud.
14:12:55 <annegentle> nickchase: it's.... facilitation is a special talent that really needs to be an outsider, but I could be swayed otherwise
14:13:01 <Sam-I-Am> regXboi: august, in australia
14:13:07 <annegentle> nickchase: there is evidence that sprint books don't bring in maintainers
14:13:11 <annegentle> nickchase: we've seen it
14:13:23 <Sam-I-Am> docs dont bring in maintainers :/
14:13:27 <regXboi> Sam-I-Am: well... that's not going to be travel, but will there be a virtual swarm?
14:13:27 <annegentle> nickchase: so I'd love to discuss further but I have pretty strong opinions on the sprints
14:13:35 <nickchase> annegentle: I completely get that; that's why they need to be good tos tart with.
14:13:37 <Sam-I-Am> regXboi: i dont know how thats going to work
14:13:46 <annegentle> nickchase: yah
14:14:00 <annegentle> regXboi: hey you like regex? :)
14:14:04 <nickchase> annegentle: we can talk about it another time, didn't mean to monopolize. :)
14:14:11 <annegentle> Let's talk about the networking guide, seems like a good segue
14:14:16 <annegentle> nickchase: sure no prob!
14:14:23 <regXboi> annegentle: it's an old handle from days of writing production OSS in perl :)
14:14:36 <annegentle> fits with our next topic anyway
14:14:37 <annegentle> #topic Review docs-specs: shared glossary and HOT template chapter in user guide
14:14:49 <annegentle> I'll take them one at a time but start with the networking one
14:15:10 <annegentle> Sam-I-Am, phil__ (that's phil hopkins) are working on an outline
14:15:17 <regXboi> Sam-I-Am: I'd be interested in the day/times to see if I could virtually drop in and help out.... but in US CDT, it might get tricky :(
14:15:20 <annegentle> Lana (loquacities) is organizing the swarm
14:15:28 <Sam-I-Am> regXboi: i'm in us/cdt too
14:15:34 <annegentle> so, regXboi you could certainly help in some capacity
14:15:34 <Sam-I-Am> we'll figure it out
14:15:44 <annegentle> Sam-I-Am: where's that outline? Did you decide whether to move it into a spec?
14:15:49 <Sam-I-Am> regXboi: just work a swing swift
14:15:54 <regXboi> sounds good - I've got some definite opinions on the networking specs :)
14:16:10 <annegentle> regXboi: so these are docs-specs we're discussing now
14:16:17 <Sam-I-Am> annegentle: i didn't decide on that yet. kind of underwater.
14:16:25 <regXboi> annegentle: yes - s/specs/doc-specs/
14:16:41 <annegentle> #link https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide
14:16:54 <annegentle> #link https://wiki.openstack.org/wiki/NetworkingGuide/TOC
14:17:01 <Sam-I-Am> annegentle: i like the idea of the doc spec
14:17:13 <annegentle> That ^^ is the TOC they're working on, that can be then made into a doc spec in the docs-spec repo
14:17:26 <annegentle> The swarm aims to fill in some of that
14:17:35 <annegentle> but a spec would be nice to state the problem statement and solution clearly
14:17:45 <regXboi> annegentle: you know, I like this - there are a bunch of neutron doc bugs that I've looked at that could concievably fit in here
14:18:06 <annegentle> regXboi: yep, absolutely
14:18:22 <annegentle> It'd be great to fit known doc bugs into the spec too, hm.
14:18:30 <annegentle> Ok, let's also talk about the two in the review queue
14:18:44 <annegentle> #link https://blueprints.launchpad.net/openstack-manuals/+spec/common-glossary-setup
14:19:04 <annegentle> #link https://review.openstack.org/#/c/104781/
14:19:05 <regXboi> well that's all goodness
14:19:59 <annegentle> I like where the common glossary one is going
14:20:04 <regXboi> I think I'm going to +1 the git submodule idea
14:20:10 <annegentle> Ok, the other one is the HOT template chapter in the user guide
14:20:15 <annegentle> regXboi: Gerrit doesn't support submodules
14:20:26 <regXboi> yeah - that's the rub :(
14:20:38 <annegentle> #link https://blueprints.launchpad.net/openstack-manuals/+spec/heat-templates
14:20:56 <annegentle> #link https://wiki.openstack.org/wiki/Documentation/blueprints/heat-templates
14:20:57 <annegentle> and
14:21:07 <annegentle> #link https://review.openstack.org/#/c/108133/
14:21:37 <gpocentek> I'll work on your comments later today annegentle
14:21:48 <annegentle> gpocentek: I had wondered on the review if the automation of the reference info is in the scope of this blueprint mainly... thanks a bunch for writing it up
14:22:19 <gpocentek> annegentle: this bp could be some kind of master bp
14:22:24 <annegentle> also, just as a general note, the specs aren't published anywhere yet, but we want them all to go to specs.openstack.org
14:22:33 <annegentle> that way, they're not "docs"
14:22:46 <regXboi> annegentle: I'll do a readthrough of both gerrits today and add some comments
14:23:21 <annegentle> regXboi: thanks!
14:23:42 <annegentle> gpocentek: I really like how you're thinking about and planning for advanced topics, they're really needed
14:24:10 <annegentle> I haven't had any further movement on the redesign or python client docs
14:24:19 <annegentle> so that's it for blueprints we know we're doing, any questions?
14:24:32 <annegentle> know we're doing specs for
14:24:35 <annegentle> I mean
14:24:44 <annegentle> there's plenty approved without assignees
14:24:56 <Sam-I-Am> need more warm bodies :)
14:24:59 <annegentle> oh and please do review Ildiko's latest work on adding ceilometer/Telemetry to the admin guide
14:25:01 <regXboi> annegentle: were you going to take a spin at fit known doc bugs into the net guide spec?
14:25:02 <Sam-I-Am> always a problem with docs
14:25:05 <gpocentek> annegentle: should we start migrating all the approved LS blueprints?
14:25:09 <gpocentek> s/LS/LP/
14:25:16 <annegentle> regXboi: do you have time to? You sound like you know them well :)
14:25:28 <regXboi> annegentle: I was taking the action :)
14:25:38 <annegentle> Sam-I-Am: we had 195 contributors last time, I don't want to hear negativity when we're growing based on the data, please
14:25:47 <annegentle> regXboi: sweet!
14:26:09 <annegentle> #action regXboi to add list of existing neutron doc bugs to the blueprint wiki page
14:26:39 <annegentle> Ok, the next topic is a public service announcement :)
14:26:41 <annegentle> #topic Summit proposals due 7/28/14
14:26:56 <annegentle> These are the proposals for the business side of the summit, not for the doc track itself
14:27:23 <annegentle> I'm thinking about data mining support cases around app devs
14:27:41 <annegentle> and slicing it with docs GA data
14:27:51 <annegentle> I know the Arch Design team is proposing a talk
14:27:57 <annegentle> anyone else with ideas?
14:28:37 <regXboi> annegentle: I'd think the data mining sprinkled with real case issues should work
14:28:48 <nickchase> I still haven't implemented the "template" talk decisions from Atlanta.
14:28:49 <annegentle> regXboi: yeah
14:28:57 <regXboi> I've come to the docs side based on the delta between docs and the SC :)
14:28:58 <annegentle> nickchase: oo remind me
14:29:06 <annegentle> nickchase: oh right the template for commit messages?
14:29:14 <annegentle> regXboi: nice!
14:29:51 <nickchase> annegentle:  yes
14:30:13 <nickchase> Need to get with you to figure out exactly what I need to do, as in what format file and who to send it to
14:30:23 <Sam-I-Am> speaking of not-done-things, i'm still trying to get the review guide up.
14:30:32 <annegentle> nickchase: yeah I think it's in the -infra area
14:31:09 <annegentle> Sam-I-Am: awesome, I heard Andreas had a start at the revising style guide? But not sure. Need to follow up.
14:31:42 <Sam-I-Am> annegentle: it was a dependency of re-organizing the conventions/style guide... so thats why i think it kind of went forgotten. but its very important.
14:32:12 <nickchase> annegentle: I figured.  I'll get with you offline and we'll push it forward
14:32:17 <regXboi> so, a process question comes to mind... does the doc team have links to cores in the various projects?
14:32:24 <annegentle> Sam-I-Am: yeah and it's possible Andreas has a start at the dependency, let's check wtih him
14:32:28 <annegentle> too bad he's not here
14:32:32 <annegentle> regXboi: yes, let me find a link
14:32:57 <annegentle> #link https://wiki.openstack.org/wiki/Documentation/ProjectDocLeads
14:33:05 <annegentle> regXboi: so if you get stuck, ask any one of those listed
14:33:15 <regXboi> annegentle: thanks - I'm thinking ahead in cases where a doc bug actually involves changing project code
14:33:16 <annegentle> regXboi: Edgar Magana especially for networking
14:33:24 <annegentle> regXboi: yep, precisely
14:33:30 <regXboi> Edgar and I have already been consulting :)
14:33:52 <annegentle> regXboi: good!
14:34:08 <annegentle> Edgar is coming to the ops meetup and we were gonna talk docs there, are you coming to that?
14:34:09 <regXboi> I don't know if folks have seen this:
14:34:22 <regXboi> annegentle: no travel budget here :(
14:34:27 <annegentle> regXboi: ah ok
14:34:28 <regXboi> I can only drop in virtually
14:34:38 <regXboi> #link https://wiki.openstack.org/wiki/Network/Meetings#Docs_.28emagana.29
14:34:43 <annegentle> Sam-I-Am: are you coming to the ops meetup?
14:34:52 <annegentle> regXboi: NICE.
14:35:03 <regXboi> I put in a bunch of initial comments on neutron doc bugs as part of the neutron mid-cycle sprint
14:35:14 <annegentle> does anyone think we need a docs proposal for the summit? I think loquacities is working on one.
14:35:35 <Sam-I-Am> annegentle: i thought so
14:35:35 <annegentle> regXboi: cool, I edited the etherpad with deeper links
14:35:47 <nickchase> I think we always need a docs proposal, just to remind people we exist
14:35:56 <nickchase> But honestly, nothing's coming to me.
14:36:03 <annegentle> Sam-I-Am: ok cool, we'll definitely work with Edgar there
14:36:10 <regXboi> do we have a troubleshooting guide?
14:36:16 <annegentle> nickchase: okay good to know. I'd hate to have a bunch when we could get one approved, ya know?
14:36:21 <regXboi> that's the obvious thing to ask for an ops summit :)
14:36:24 <annegentle> regXboi: no, troubleshooting chapters
14:36:34 <regXboi> ok... *should* we have a troubleshooting guide ;)
14:37:05 <annegentle> regXboi: you'll find I get a lot of requests for new "books" and usually tell people to write chapters, BUT, after networking guide troubleshooting guide COULD be a candidate.
14:37:36 <regXboi> annegentle: understood - my thought is that if I'm going to do a proposal for an ops session, it should be ops related
14:37:42 <regXboi> and troubleshooting is the obvious candidate
14:37:54 <regXboi> especially as I think (if done well) it goes way beyond a chapter
14:38:04 <annegentle> regXboi: oh I see, yeah, have you added it to the ops meetup etherpad?
14:38:18 <regXboi> annegentle: no - just thinking out loud here
14:38:24 <annegentle> #link https://etherpad.openstack.org/p/SAT-ops-meetup
14:38:26 <annegentle> great idea
14:38:58 <regXboi> somebody is beating me to it :)
14:39:11 <annegentle> heh
14:39:14 <annegentle> "Would a troubleshooting guide be a good "next" deliverable after ML2 is properly documented?"
14:39:19 <regXboi> works for me
14:39:23 <annegentle> because honestly ml2 isn't properly documented :)
14:39:35 <annegentle> ok
14:39:36 <regXboi> um: I'd argue neutron isn't properly documented :)
14:39:37 <annegentle> #topic Doc tools updates
14:39:49 <annegentle> regXboi: yes I just put things into buckets :)
14:39:56 <regXboi> +1
14:40:10 <annegentle> I don't have a lot to report on doc tools, just keep an eye on the mailing list about the training guide xi:includes
14:40:17 <annegentle> any training teammates here?
14:40:22 <nickchase> maybe that's the big thing: we need to get some help for Sam-I-Am and Phil
14:40:31 <regXboi> annegentle: is there any complaints if (as a newbie) I take a pass through the doc tools wiki and make it more clear?
14:40:47 <annegentle> regXboi: I'd be fine with that, which page?
14:41:02 <regXboi> annegentle: I was going to start at the beginning and ...
14:41:17 <regXboi> i.e. walk through the set up steps and make notes where things do and don't work
14:41:58 <annegentle> regXboi: sure
14:42:05 <Sam-I-Am> regXboi: do i know you from anywhere?
14:42:32 <regXboi> Sam-I-Am: not sure :) - I'm a complete ludite when it comes to thinks like linked in, etc. :)
14:42:44 <regXboi> but I do have an RFC or three to my name
14:42:47 <annegentle> regXboi: ever get to the summits?
14:42:56 <annegentle> Oh I'll just open it up
14:43:01 <annegentle> #topic Open discussion
14:43:15 <Sam-I-Am> regXboi: not new to neutron, but new to docs
14:43:16 <Sam-I-Am> ?
14:43:18 <regXboi> annegentle: not to date - may be in Paris - it depends on presentation proposals, etc.
14:43:37 <regXboi> Sam-I-Am: (a) sorta (b) not really
14:43:57 * regXboi has about 25 years in networking and has worn *many* hats in that time :)
14:44:17 <Sam-I-Am> cool. most people who work on openstack don't have much networking background.
14:44:23 <annegentle> nice
14:44:27 <Sam-I-Am> more networking docs people = yay
14:44:45 <annegentle> thanks regXboi! (love the handle still, hahaha)
14:44:53 <annegentle> I still need a better casual friday nick
14:44:56 <regXboi> yes - I came here because the existing neutron docs don't quite cover what RTSC tells you :)
14:45:19 <Sam-I-Am> regXboi: we should chat a bit in #openstack-doc
14:45:27 <Sam-I-Am> i'll introduce you to phil
14:45:29 <annegentle> RTSC = read the source code?
14:45:34 <regXboi> Sam-I-Am: I'll add it to my channels I drop in on
14:45:38 <regXboi> annegentle: yes
14:45:49 <annegentle> ok, I'm such a good acronym translator :)
14:45:52 <Sam-I-Am> regXboi: also #openstack is good if you like helping people. lots of networking problems.
14:46:01 <annegentle> alrightly let's get back 15 mins and move it over to #openstack-doc
14:46:05 <annegentle> #endmeeting