19:01:13 <ShillaSaebi> #startmeeting docteam
19:01:14 <openstack> Meeting started Wed May 11 19:01:13 2016 UTC and is due to finish in 60 minutes.  The chair is ShillaSaebi. Information about MeetBot at http://wiki.debian.org/MeetBot.
19:01:16 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
19:01:18 <openstack> The meeting name has been set to 'docteam'
19:01:21 <njohnston> o/
19:01:23 <ShillaSaebi> Hello! Anyone here for the US docs meeting?
19:01:27 <ShillaSaebi> hi njohnston!
19:01:35 <njohnston> Hello ShillaSaebi
19:02:06 <Sam-I-Am> hellooooo
19:02:09 <strigazi> o/
19:02:46 <Sam-I-Am> anyone home?
19:02:56 <njohnston> ShillaSaebi and I are here
19:03:03 <ShillaSaebi> hello everyone
19:03:07 <ShillaSaebi> thank you for joining
19:03:13 <ShillaSaebi> lets go ahead and get started
19:03:30 <ShillaSaebi> #topic Action items from the last meeting
19:03:33 <ShillaSaebi> welp I cant think of any
19:03:41 <Sam-I-Am> its been a while
19:03:44 <ShillaSaebi> Am i missing any action items? if so let me know
19:03:55 <ShillaSaebi> yeah we had the summit and such so I don't think there were any
19:03:57 <Sam-I-Am> action item... survive summit.
19:03:58 <ShillaSaebi> but I just want to make sure
19:04:03 <ShillaSaebi> yes exactly
19:04:09 <njohnston> Sam-I-Am: +1
19:04:11 <ShillaSaebi> hopefully everyone is alive and well, survived and back to normal lives
19:04:25 <strigazi> Is there an agenda for today's meeting?
19:04:44 <ShillaSaebi> #topic Specs in review
19:04:49 <ShillaSaebi> #link https://review.openstack.org/#/q/status:open+project:openstack/docs-specs,n,z
19:04:52 <Sam-I-Am> strigazi: there should be
19:04:58 <Sam-I-Am> hopefully its been updated
19:05:04 <ShillaSaebi> strigazi yes the agenda is posted on the docs wiki for meetinsg
19:05:08 <ShillaSaebi> one second ill grab the link
19:05:14 <ShillaSaebi> #link https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting
19:05:26 <ShillaSaebi> please take a look at the specs in review
19:05:50 <ShillaSaebi> There's one in there for the architecture guide by Shaun OMeara
19:06:32 <strigazi> One is mine
19:06:45 <strigazi> but I'll abandon it since 301284 is merged
19:07:12 <ShillaSaebi> ok strigazi looks like the next step was to abandon right
19:07:12 <ShillaSaebi> ok
19:07:15 <ShillaSaebi> that sounds good
19:07:55 <strigazi> I pushed today in our repo (magnum) and wait for the newton install-guide spec
19:08:08 <strigazi> To be finalized
19:08:46 <ShillaSaebi> ok
19:08:54 <ShillaSaebi> that sounds good
19:09:31 <ShillaSaebi> ok next topic
19:09:34 <ShillaSaebi> #topic Specialty Teams
19:09:45 <ShillaSaebi> #link https://etherpad.openstack.org/p/Speciality_Team_Reports
19:10:03 <ShillaSaebi> the specialty team reports should be updated to the Etherpad above
19:10:14 <ShillaSaebi> if we have leads that want to discuss anything further for the specialty teams or anything to share, that would be great
19:10:20 <ShillaSaebi> feel free
19:10:39 <ShillaSaebi> the notes I put in for the ops/arch guide specialty team are pretty extensive, ask questions if you need to though
19:10:53 <Sam-I-Am> well, i'm just chugging along with the networking guide
19:11:05 <Sam-I-Am> hopefully get more time to work on it since i'm not involved in the install guide
19:11:21 <ShillaSaebi> yes!
19:11:31 <ShillaSaebi> and Edgar mentioned that the meeting wasn't held so we'll know more next time
19:12:29 <ShillaSaebi> :)
19:12:32 <ShillaSaebi> anything else on the specialty teams?
19:12:38 <Sam-I-Am> newp
19:12:40 <ShillaSaebi> anyone else want to add any details or notes ?
19:12:48 <ShillaSaebi> ok I don't have anything else on them either
19:13:01 <Sam-I-Am> i have some other stuff, but not specialty team related
19:13:11 <ShillaSaebi> ok our agenda is pretty light today so we will have time
19:13:27 <Sam-I-Am> so is attendance, something i wish we could fix
19:14:00 <ShillaSaebi> yeah I thought with the time change being more convenient, we'd have more join
19:14:07 <shauno__> I would like to chat about the arch-guide blueprint if possible?
19:14:08 <ShillaSaebi> the reminders are hit or miss
19:14:25 <ShillaSaebi> sure
19:14:31 <ShillaSaebi> let me grab the newton etherpad to share
19:14:34 <ShillaSaebi> and then we can do an open discussion
19:15:31 <ShillaSaebi> #link https://etherpad.openstack.org/p/austin-docs-newtonplan
19:15:36 <ShillaSaebi> here is the newton planning etherpad
19:15:43 <ShillaSaebi> i just wanted to share that, in case you didn't go to the summit
19:16:11 <ShillaSaebi> I don't have anything else on that topic we can certainly move to an open discussion
19:16:24 <Sam-I-Am> ok
19:16:41 <ShillaSaebi> ok anyone have any questions before we open up the discussion?
19:16:49 <ShillaSaebi> going once
19:16:51 <ShillaSaebi> going twice
19:16:59 <ShillaSaebi> ok #topic Open Discussion
19:17:06 <Sam-I-Am> yep
19:17:07 <Sam-I-Am> so...
19:17:28 <Sam-I-Am> i spoke with a bunch of devs at the summit, trying to determine the reason for slim contributions to central docs
19:17:48 <Sam-I-Am> docbook used to be the primary problem, and i think that has permanently scared a number of projects/devs away
19:17:57 <Sam-I-Am> as much as we try, they're not coming back
19:18:06 <Sam-I-Am> now we're using rst, so what's the problem?
19:18:24 <ShillaSaebi> im not sure
19:18:25 <ShillaSaebi> do they know we changed
19:18:29 <Sam-I-Am> turns out they're not happy with the review process. its often cumbersome and slow, and most of them just want to push the content and move on.
19:18:35 <ShillaSaebi> have we communicated that to them?
19:18:38 <ShillaSaebi> ohhh
19:18:43 <Sam-I-Am> i think they do, but i'm not entirely sure
19:18:44 <ShillaSaebi> ok
19:18:48 <ShillaSaebi> I can see that
19:18:54 <ShillaSaebi> sometimes we nitpick on grammar and spelling
19:18:56 <ShillaSaebi> but we need the content
19:19:01 <Sam-I-Am> problem is, it takes a LOT of effort to fix several years of frustration
19:19:06 <ShillaSaebi> maybe we can just take the content then patch later to fix the nits
19:19:16 <Sam-I-Am> well, thats where my email to the dev list comes in
19:19:19 <ShillaSaebi> is it a culture issue with docs?
19:19:22 <ShillaSaebi> ok
19:19:31 <shauno__> I could we delegate some of the review process to make it easier?
19:19:37 <Sam-I-Am> #link http://lists.openstack.org/pipermail/openstack-dev/2016-May/094390.html
19:19:45 <njohnston> Well, I'm a new-ish developer (as of Liberty) and I have felt like the docs area is really easy to contribute to, and the docs team is less nitpicky than the code reviewers.  With 40% of developers being new each release, it may just be a matter of time before those new ones become the senior devs we need writing for most intense docs.
19:20:21 <shauno__> Or rather faster?
19:20:31 <strigazi> As a new contributor I didn't it too difficult or slow
19:20:34 <Sam-I-Am> njohnston: i think new-ish people have fewer issues because they werent around in the docbook days
19:20:55 <ShillaSaebi> i see
19:20:55 <njohnston> Also, the more teams go to a "no doc, no merge" the better, but you can onky lead that horse to water.
19:21:09 <Sam-I-Am> but i think the FUD spreads from long-standing developers to new developers
19:21:14 <Sam-I-Am> "oh, those docs people..." etc
19:21:39 <njohnston> Sam-I-Am: I agree.  If Docbook was as bad as WADL then I can completely see that.  Contributing to the API guide was a nightmare last cycle.
19:22:08 <Sam-I-Am> we need to get projects on board with the importance of docs, and putting the most important ones (for the prime audience of operators/users) in a central place with an efficient structure/layout
19:22:32 <Sam-I-Am> njohnston: there are more no doc no merge, but docs are going into the devref instead of places where operators can find them
19:22:46 <Sam-I-Am> merely because there's less friction to contribute docs to the same repo in which the project resides
19:23:08 <Sam-I-Am> i think the friction is a) where does my stuff go and b) the review process is hard
19:23:17 <Sam-I-Am> so my post to the dev list at least aims to fix (b)
19:23:21 <njohnston> I also feel like DocImpact has created a cop-out mentality of "oh, docs are something to handle whenever *waves hands*".  Just my personal opinion.
19:23:48 <Sam-I-Am> njohnston: yeah, but docimpact is better than it used to be. it used to open a bug in openstack-manuals, so no one saw it except docs.
19:23:56 <Sam-I-Am> now it opens a bug in the project repo, but that assumes someone uses docimpact
19:24:03 <Sam-I-Am> keystone, for example, doesnt bother to use it
19:24:13 <Sam-I-Am> so a lot of changes happened in mitaka that no one caught
19:24:25 <Sam-I-Am> some projects think relnotes replace docimpact
19:24:28 <Sam-I-Am> which is also a problem
19:24:34 <Sam-I-Am> so a lot of this is communication problems
19:24:57 <njohnston> I didn't use DocImpact, but I had a simultaneous patch in openstack-manuals with a cross-repo Depends-On.  I feel like that is the ideal situation, but I can't figure out how to articulate persuasuvely.
19:25:16 <Sam-I-Am> thats really nice :)
19:25:21 <Sam-I-Am> and probably the way it should be
19:25:53 <Sam-I-Am> but... as much as openstack needs to appear like a coherent framework/product, most of the projects/devs dont see it that way
19:25:57 <ShillaSaebi> I'm interested in seeing what responses will look like coming from the developers
19:26:02 <ShillaSaebi> in response to your proposed solution
19:26:05 <ShillaSaebi> I think it looks good
19:26:13 <Sam-I-Am> ShillaSaebi: not many responses yet :/
19:26:16 <Sam-I-Am> which is a bit concerning
19:26:19 <ShillaSaebi> yeah
19:26:51 <njohnston> Can we ask the documentation liasons to assess the moods of their respective dev communities?
19:27:01 <Sam-I-Am> looking at the number of projects that seem to contribute docs only to their own repos, i sort of wonder if a lot of them have written central docs off as a non-starter
19:27:20 <ShillaSaebi> we can reach out to the leads for the projects and ask
19:27:32 <Sam-I-Am> njohnston: that's a good idea, but its interesting that about zero of those liaisons ever attend these meetings
19:27:48 <njohnston> Sam-I-Am: I was curious why I never see those folks around
19:28:01 <njohnston> except for emagana
19:28:13 <Sam-I-Am> your guess is a good as mine, but since i've been around, involvement with docs (even by docs people) has waned for some reason.
19:28:13 <ShillaSaebi> can we find out the people who contribute docs only to their repo
19:28:16 <strigazi> btw since today I'm the liaison for magnum
19:28:20 <ShillaSaebi> maybe put together a list? and reach out to them?
19:28:22 <Sam-I-Am> strigazi: welcome :)
19:28:37 <emagana> thanks njohnston  ;-)
19:28:47 <Sam-I-Am> we definitely need to do something to drum up support for docs and get people on the right page, i just havent figured out how
19:28:51 <njohnston> emagana: Credit where credit is due :-)
19:28:54 <ShillaSaebi> Sam-I-Am you are right about the decrease, I can't back it by numbers but I can say that I've noticed the same thing
19:29:45 <Sam-I-Am> well, just looking at doc meeting attendance is one thing
19:29:55 <Sam-I-Am> core reviews are a bit slow too
19:30:10 <ShillaSaebi> we can look at the turnaround times
19:30:12 <ShillaSaebi> and compare
19:30:51 <njohnston> I also see a lot of new projects getting created, by mitosis or inception.  Is there a 'so you have a new project, here's how you integrate into docs' for new projects?  Like tacker, or kolla, or higgins...
19:31:06 <ShillaSaebi> no there is not, i don't think
19:31:08 <ShillaSaebi> but thats a great idea
19:31:11 <njohnston> sorry I realize that is probably a tangent
19:31:17 <Sam-I-Am> this is all good
19:31:26 <Sam-I-Am> its possible a lot of these projects dont know about docs
19:31:37 <Sam-I-Am> and probably arent writing them either, at least initially
19:32:04 <Sam-I-Am> i've sort of pushed the TC to adopt the no docs no merge thing (or you're not a project) ... but i dont think it'll get much traction
19:32:49 <strigazi> docs are a key factor for Project acceptance, we needed an install-guide so we reached out
19:33:12 <Sam-I-Am> install guides are definitely important because it enables new people to use your project
19:33:21 <ShillaSaebi> right
19:33:29 <ShillaSaebi> have we started a thread on this topic on the docs ML yet
19:33:29 <Sam-I-Am> most of them are "heres how it works in devstack" which gives operators no idea how to deploy it realistically
19:34:03 <ShillaSaebi> We should take it to the ML and look at perspective from other members of docs as well
19:34:14 <Sam-I-Am> ShillaSaebi: not this specific topic. not everyone reads the docs ml, at least not devs.
19:34:15 <vhoward> ML is a good idea
19:34:48 <ShillaSaebi> yeah we can start from the docs ML and see if everyone agrees that this is a problem
19:34:50 <Sam-I-Am> thus, i'm wondering if we should discuss the issues and the approach on the docs ML, then post those potential solutions to the dev list
19:34:51 <ShillaSaebi> or majority agrees
19:34:52 <strigazi> At least for the install-guide, a clear guide on how to contribute will play a significant role
19:34:54 <ShillaSaebi> and we can discuss ways to mitigate
19:35:03 <ShillaSaebi> I agree
19:35:50 <Sam-I-Am> strigazi: thats currently being restructured. most of the problem around it is the fine line between ease of installation (distro packages) and supporting the big tent (most projects dont have distro packages)
19:36:47 <strigazi> I'm not sure if distro packages are the only way to go, puppet, ansible etc are used widely
19:36:50 <njohnston> Sam-I-Am: Are other guides having a similar restructuring?  I hope to avoid a repeat of the email thread "Our Install Guides Only Cover Defcore - What about big tent?" except about the Ops guide or some other guide.
19:36:52 <Sam-I-Am> aight, so do you want me to start this thread?
19:36:55 <ShillaSaebi> I think docs should also start going to some of those dev meetings and acting as a liason between the projects and docs
19:37:09 <ShillaSaebi> yeah I think we have tons of great ideas on how we can potentially resolve this
19:37:35 <Sam-I-Am> ShillaSaebi: its actually easier for devs/liaisons to attend 1 docs meeting rather than a handful of docs people trying to attend every project's meeting
19:37:41 <Sam-I-Am> we just dont have enough horsepower
19:37:48 <strigazi> +1
19:37:52 <njohnston> +1
19:37:53 <Sam-I-Am> i attend neutron's meetings, but thats about all i can handle
19:37:57 <ShillaSaebi> I'd like to keep this going and then we can put together a clear action plan with steps on what we need to do to make the central docs a happy place to contribute for devs
19:38:01 <ShillaSaebi> +1
19:38:02 <vhoward> +1
19:38:07 <njohnston> well, there are so damn many neutron meetings
19:38:12 <ShillaSaebi> lol
19:38:24 <Sam-I-Am> njohnston: well, there's some talk about more docs going into project repos
19:38:27 <ShillaSaebi> #action Sam-I-Am to start thread on dev doc contributions
19:38:31 <Sam-I-Am> the install guide is sort of the first thing to try it
19:39:08 <strigazi> Yes, and we it the restructure like hiting on a wall
19:39:22 <Sam-I-Am> strigazi: it'll probably come down to installing from source... somehow. some of the deployment tools are nice, but we cant necessarily be opinionated there, and there's also a chance those deployment tools dont support all projects
19:39:38 <strigazi> true
19:40:08 <Sam-I-Am> problem with distro packages is you cant easily mix them with upstream pip
19:40:10 <strigazi> We'll try to add as musch as possible in our repo and see what can be pushed in doo
19:40:49 <Sam-I-Am> so it'll probably end up as a venv-based source install of all services with some hand-holding to provide things like init scripts
19:40:59 <Sam-I-Am> beyond that, i dont know
19:41:10 <ShillaSaebi> i have to step away for a few minutes, ill be back
19:41:13 <Sam-I-Am> the key is not making openstack so difficult to install for people who just want to try it
19:41:18 <Sam-I-Am> ShillaSaebi: ok, i think we're close to done
19:41:28 <ShillaSaebi> ok and strigazi i didnt forget about you
19:41:37 <ShillaSaebi> do you still want to bring up the patch?
19:41:39 <Sam-I-Am> i'll try to put together an e-mail outlining the problems i think we're seeing... and reference my post to the dev ml
19:41:53 <ShillaSaebi> Sam-I-Am I am looking fwd to it
19:42:17 * Sam-I-Am steps down from soap box
19:42:19 <ShillaSaebi> I hope this is the start of increased participation and ease for our developers
19:42:28 <ShillaSaebi> ok strigazi you are up
19:42:28 <njohnston> so say we all
19:42:33 <Sam-I-Am> me too. its hard trying to fix the mess.
19:42:36 <ShillaSaebi> we have 15 minutes
19:42:40 <Sam-I-Am> there's just a lot of bad feelings
19:42:59 <Sam-I-Am> feel free to chime in on that dev list post
19:43:05 <Sam-I-Am> maybe spur some more talk
19:43:29 <ShillaSaebi> njohnston and vhoward you guys are excellent example
19:43:30 <ShillaSaebi> examples*
19:43:44 <ShillaSaebi> not of having bad feelings but of being developers who contribute to docs
19:43:55 <vhoward> thank you for clarifying
19:43:59 <ShillaSaebi> lol
19:44:11 <vhoward> (╯°□°）╯︵ ┻━┻
19:44:19 <ShillaSaebi> hopefully no bad feelings
19:44:39 <vhoward> thanks shilla
19:44:42 <ShillaSaebi> ¯\_(ツ)_/¯
19:44:49 <Sam-I-Am> theres a few... they need to spread the word that we dont bite
19:44:51 <njohnston> Docs are a part any sane Definition of Done.  In my mind, that's all there is to it.
19:45:03 <ShillaSaebi> +1
19:45:07 <vhoward> agreed
19:45:23 <Sam-I-Am> thats what i like to hear. can't use it if you cant install it.
19:45:28 <Sam-I-Am> or even dont know about it
19:45:52 <ShillaSaebi> yeah
19:45:56 <ShillaSaebi> cool! glad we are all on the same page
19:45:59 <Sam-I-Am> yep
19:46:06 <ShillaSaebi> ok #topic Still open discussion
19:46:09 <Sam-I-Am> we need a docs advocation team
19:46:33 <ShillaSaebi> I was thinking we wear shirts or something that tells ppl we are part of docs at the next summit
19:46:47 <Sam-I-Am> well then we might get murdered :)
19:46:47 <ShillaSaebi> so ppl can come talk to us and ask any questions if need be
19:46:50 <ShillaSaebi> lol
19:47:06 <ShillaSaebi> we'll be fine, we can handle it
19:47:21 <ShillaSaebi> ok anything else anyone wants to bring up?
19:47:30 <ShillaSaebi> before I give everyone their 10 minutes back?
19:47:43 <ShillaSaebi> going once?
19:47:51 <ShillaSaebi> going twice?
19:48:19 <ShillaSaebi> ok if not then we can adjourn this meeting
19:48:23 <ShillaSaebi> thank you everyone for joining
19:48:29 <vhoward> thanks
19:48:37 <ShillaSaebi> :D
19:48:39 <strigazi> see in the next meeting
19:48:39 <njohnston> \o
19:48:44 <shauno__> Cheers
19:48:49 <ShillaSaebi> have a good rest of week and see you at the next meeting
19:48:50 <vhoward> o/
19:48:53 <ShillaSaebi> #endmeeting