19:01:13 #startmeeting docteam 19:01:14 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 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 19:01:18 The meeting name has been set to 'docteam' 19:01:21 o/ 19:01:23 Hello! Anyone here for the US docs meeting? 19:01:27 hi njohnston! 19:01:35 Hello ShillaSaebi 19:02:06 hellooooo 19:02:09 o/ 19:02:46 anyone home? 19:02:56 ShillaSaebi and I are here 19:03:03 hello everyone 19:03:07 thank you for joining 19:03:13 lets go ahead and get started 19:03:30 #topic Action items from the last meeting 19:03:33 welp I cant think of any 19:03:41 its been a while 19:03:44 Am i missing any action items? if so let me know 19:03:55 yeah we had the summit and such so I don't think there were any 19:03:57 action item... survive summit. 19:03:58 but I just want to make sure 19:04:03 yes exactly 19:04:09 Sam-I-Am: +1 19:04:11 hopefully everyone is alive and well, survived and back to normal lives 19:04:25 Is there an agenda for today's meeting? 19:04:44 #topic Specs in review 19:04:49 #link https://review.openstack.org/#/q/status:open+project:openstack/docs-specs,n,z 19:04:52 strigazi: there should be 19:04:58 hopefully its been updated 19:05:04 strigazi yes the agenda is posted on the docs wiki for meetinsg 19:05:08 one second ill grab the link 19:05:14 #link https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting 19:05:26 please take a look at the specs in review 19:05:50 There's one in there for the architecture guide by Shaun OMeara 19:06:32 One is mine 19:06:45 but I'll abandon it since 301284 is merged 19:07:12 ok strigazi looks like the next step was to abandon right 19:07:12 ok 19:07:15 that sounds good 19:07:55 I pushed today in our repo (magnum) and wait for the newton install-guide spec 19:08:08 To be finalized 19:08:46 ok 19:08:54 that sounds good 19:09:31 ok next topic 19:09:34 #topic Specialty Teams 19:09:45 #link https://etherpad.openstack.org/p/Speciality_Team_Reports 19:10:03 the specialty team reports should be updated to the Etherpad above 19:10:14 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 feel free 19:10:39 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 well, i'm just chugging along with the networking guide 19:11:05 hopefully get more time to work on it since i'm not involved in the install guide 19:11:21 yes! 19:11:31 and Edgar mentioned that the meeting wasn't held so we'll know more next time 19:12:29 :) 19:12:32 anything else on the specialty teams? 19:12:38 newp 19:12:40 anyone else want to add any details or notes ? 19:12:48 ok I don't have anything else on them either 19:13:01 i have some other stuff, but not specialty team related 19:13:11 ok our agenda is pretty light today so we will have time 19:13:27 so is attendance, something i wish we could fix 19:14:00 yeah I thought with the time change being more convenient, we'd have more join 19:14:07 I would like to chat about the arch-guide blueprint if possible? 19:14:08 the reminders are hit or miss 19:14:25 sure 19:14:31 let me grab the newton etherpad to share 19:14:34 and then we can do an open discussion 19:15:31 #link https://etherpad.openstack.org/p/austin-docs-newtonplan 19:15:36 here is the newton planning etherpad 19:15:43 i just wanted to share that, in case you didn't go to the summit 19:16:11 I don't have anything else on that topic we can certainly move to an open discussion 19:16:24 ok 19:16:41 ok anyone have any questions before we open up the discussion? 19:16:49 going once 19:16:51 going twice 19:16:59 ok #topic Open Discussion 19:17:06 yep 19:17:07 so... 19:17:28 i spoke with a bunch of devs at the summit, trying to determine the reason for slim contributions to central docs 19:17:48 docbook used to be the primary problem, and i think that has permanently scared a number of projects/devs away 19:17:57 as much as we try, they're not coming back 19:18:06 now we're using rst, so what's the problem? 19:18:24 im not sure 19:18:25 do they know we changed 19:18:29 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 have we communicated that to them? 19:18:38 ohhh 19:18:43 i think they do, but i'm not entirely sure 19:18:44 ok 19:18:48 I can see that 19:18:54 sometimes we nitpick on grammar and spelling 19:18:56 but we need the content 19:19:01 problem is, it takes a LOT of effort to fix several years of frustration 19:19:06 maybe we can just take the content then patch later to fix the nits 19:19:16 well, thats where my email to the dev list comes in 19:19:19 is it a culture issue with docs? 19:19:22 ok 19:19:31 I could we delegate some of the review process to make it easier? 19:19:37 #link http://lists.openstack.org/pipermail/openstack-dev/2016-May/094390.html 19:19:45 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 Or rather faster? 19:20:31 As a new contributor I didn't it too difficult or slow 19:20:34 njohnston: i think new-ish people have fewer issues because they werent around in the docbook days 19:20:55 i see 19:20:55 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 but i think the FUD spreads from long-standing developers to new developers 19:21:14 "oh, those docs people..." etc 19:21:39 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 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 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 merely because there's less friction to contribute docs to the same repo in which the project resides 19:23:08 i think the friction is a) where does my stuff go and b) the review process is hard 19:23:17 so my post to the dev list at least aims to fix (b) 19:23:21 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 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 now it opens a bug in the project repo, but that assumes someone uses docimpact 19:24:03 keystone, for example, doesnt bother to use it 19:24:13 so a lot of changes happened in mitaka that no one caught 19:24:25 some projects think relnotes replace docimpact 19:24:28 which is also a problem 19:24:34 so a lot of this is communication problems 19:24:57 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 thats really nice :) 19:25:21 and probably the way it should be 19:25:53 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 I'm interested in seeing what responses will look like coming from the developers 19:26:02 in response to your proposed solution 19:26:05 I think it looks good 19:26:13 ShillaSaebi: not many responses yet :/ 19:26:16 which is a bit concerning 19:26:19 yeah 19:26:51 Can we ask the documentation liasons to assess the moods of their respective dev communities? 19:27:01 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 we can reach out to the leads for the projects and ask 19:27:32 njohnston: that's a good idea, but its interesting that about zero of those liaisons ever attend these meetings 19:27:48 Sam-I-Am: I was curious why I never see those folks around 19:28:01 except for emagana 19:28:13 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 can we find out the people who contribute docs only to their repo 19:28:16 btw since today I'm the liaison for magnum 19:28:20 maybe put together a list? and reach out to them? 19:28:22 strigazi: welcome :) 19:28:37 thanks njohnston ;-) 19:28:47 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 emagana: Credit where credit is due :-) 19:28:54 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 well, just looking at doc meeting attendance is one thing 19:29:55 core reviews are a bit slow too 19:30:10 we can look at the turnaround times 19:30:12 and compare 19:30:51 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 no there is not, i don't think 19:31:08 but thats a great idea 19:31:11 sorry I realize that is probably a tangent 19:31:17 this is all good 19:31:26 its possible a lot of these projects dont know about docs 19:31:37 and probably arent writing them either, at least initially 19:32:04 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 docs are a key factor for Project acceptance, we needed an install-guide so we reached out 19:33:12 install guides are definitely important because it enables new people to use your project 19:33:21 right 19:33:29 have we started a thread on this topic on the docs ML yet 19:33:29 most of them are "heres how it works in devstack" which gives operators no idea how to deploy it realistically 19:34:03 We should take it to the ML and look at perspective from other members of docs as well 19:34:14 ShillaSaebi: not this specific topic. not everyone reads the docs ml, at least not devs. 19:34:15 ML is a good idea 19:34:48 yeah we can start from the docs ML and see if everyone agrees that this is a problem 19:34:50 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 or majority agrees 19:34:52 At least for the install-guide, a clear guide on how to contribute will play a significant role 19:34:54 and we can discuss ways to mitigate 19:35:03 I agree 19:35:50 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 I'm not sure if distro packages are the only way to go, puppet, ansible etc are used widely 19:36:50 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 aight, so do you want me to start this thread? 19:36:55 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 yeah I think we have tons of great ideas on how we can potentially resolve this 19:37:35 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 we just dont have enough horsepower 19:37:48 +1 19:37:52 +1 19:37:53 i attend neutron's meetings, but thats about all i can handle 19:37:57 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 +1 19:38:02 +1 19:38:07 well, there are so damn many neutron meetings 19:38:12 lol 19:38:24 njohnston: well, there's some talk about more docs going into project repos 19:38:27 #action Sam-I-Am to start thread on dev doc contributions 19:38:31 the install guide is sort of the first thing to try it 19:39:08 Yes, and we it the restructure like hiting on a wall 19:39:22 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 true 19:40:08 problem with distro packages is you cant easily mix them with upstream pip 19:40:10 We'll try to add as musch as possible in our repo and see what can be pushed in doo 19:40:49 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 beyond that, i dont know 19:41:10 i have to step away for a few minutes, ill be back 19:41:13 the key is not making openstack so difficult to install for people who just want to try it 19:41:18 ShillaSaebi: ok, i think we're close to done 19:41:28 ok and strigazi i didnt forget about you 19:41:37 do you still want to bring up the patch? 19:41:39 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 Sam-I-Am I am looking fwd to it 19:42:17 * Sam-I-Am steps down from soap box 19:42:19 I hope this is the start of increased participation and ease for our developers 19:42:28 ok strigazi you are up 19:42:28 so say we all 19:42:33 me too. its hard trying to fix the mess. 19:42:36 we have 15 minutes 19:42:40 there's just a lot of bad feelings 19:42:59 feel free to chime in on that dev list post 19:43:05 maybe spur some more talk 19:43:29 njohnston and vhoward you guys are excellent example 19:43:30 examples* 19:43:44 not of having bad feelings but of being developers who contribute to docs 19:43:55 thank you for clarifying 19:43:59 lol 19:44:11 (╯°□°）╯︵ ┻━┻ 19:44:19 hopefully no bad feelings 19:44:39 thanks shilla 19:44:42 ¯\_(ツ)_/¯ 19:44:49 theres a few... they need to spread the word that we dont bite 19:44:51 Docs are a part any sane Definition of Done. In my mind, that's all there is to it. 19:45:03 +1 19:45:07 agreed 19:45:23 thats what i like to hear. can't use it if you cant install it. 19:45:28 or even dont know about it 19:45:52 yeah 19:45:56 cool! glad we are all on the same page 19:45:59 yep 19:46:06 ok #topic Still open discussion 19:46:09 we need a docs advocation team 19:46:33 I was thinking we wear shirts or something that tells ppl we are part of docs at the next summit 19:46:47 well then we might get murdered :) 19:46:47 so ppl can come talk to us and ask any questions if need be 19:46:50 lol 19:47:06 we'll be fine, we can handle it 19:47:21 ok anything else anyone wants to bring up? 19:47:30 before I give everyone their 10 minutes back? 19:47:43 going once? 19:47:51 going twice? 19:48:19 ok if not then we can adjourn this meeting 19:48:23 thank you everyone for joining 19:48:29 thanks 19:48:37 :D 19:48:39 see in the next meeting 19:48:39 \o 19:48:44 Cheers 19:48:49 have a good rest of week and see you at the next meeting 19:48:50 o/ 19:48:53 #endmeeting