14:03:31 <annegentle> #startmeeting docteam
14:03:32 <openstack> Meeting started Thu Feb 26 14:03:31 2015 UTC and is due to finish in 60 minutes.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:03:33 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
14:03:35 <annegentle> there we go
14:03:36 <openstack> The meeting name has been set to 'docteam'
14:03:44 <annegentle> #topic Action items from last meeting
14:03:58 <Sam-I-Am> oh, its in here.
14:04:00 <Sam-I-Am> fancy
14:04:12 <AJaeger> cool
14:04:40 <annegentle> welcome nickchase
14:04:45 <annegentle> the last meeting had
14:04:47 <annegentle> asettle to investigate arch guide as a project for a docs swarm
14:04:47 <nickchase> Morning, all.
14:04:56 <annegentle> she emailed me and I think it's a great idea, so sure!
14:05:19 <annegentle> She's also looking for a location for them to meet up informally on the other side of the world
14:05:38 <annegentle> and then someone from RedHat is booking a spot for their swarm Aug 13-14
14:05:58 <annegentle> from 2 weeks ago we had no action items
14:06:18 <annegentle> so, let's talk about review guidelines
14:06:22 <annegentle> #topic Review guidelines
14:06:43 <annegentle> anyone want to start or do you want me to do a recap?
14:06:52 <nickchase> I think a recap is probably in order.
14:07:18 <annegentle> Okay, how far back? We've had difficulties with people being frustrated with doc reviews for a while, going to Tom's ranty rant after the summit :)
14:07:38 <annegentle> Then last week nickchase also expressed frustration on the mailing list -- with nit picks mostly
14:07:55 <Sam-I-Am> the review guide on the wiki goes back pre-paris
14:08:14 <openstackgerrit> Merged openstack/openstack-manuals: Fix accidental change in neutron id  https://review.openstack.org/159302
14:08:18 <annegentle> ah yes Sam-I-Am
14:08:28 <annegentle> we had a discussion in Atlanta that resulted in the Wiki page at:
14:08:52 <annegentle> #link https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines
14:09:01 <Sam-I-Am> it was  intended to make the juno install guide go in nice and easy during the rush period
14:09:02 <annegentle> any other context or history
14:09:54 <AJaeger> not as an excuse, just to set perspective: Compared to some integrated projects, it's very easy to get patches into the manuals
14:10:06 <AJaeger> Both from the setup perspective as well as how we review stuff
14:10:11 <annegentle> yes I agree completely, and was wanting to bring that up as well
14:10:20 <AJaeger> That's why we get many new folks - and some that only do a single patch
14:10:23 <Sam-I-Am> yeah we're easy :)
14:10:32 <AJaeger> So, we help onboarding other contributors into OpenStack.
14:10:44 <annegentle> our timing is good, is our accuracy good?
14:10:52 <nickchase> That's one way of looking at it. :)
14:10:55 <AJaeger> If they get scared by us, they wouldn't survive the integrated projects ;)
14:11:02 <annegentle> heh we're the nice ones
14:11:11 <AJaeger> Still I would love to have them onboarded
14:11:21 <nickchase> Yes, you know, that's a great way to think about it.
14:11:27 <Sam-I-Am> a lot of people get their ATCs with docs
14:11:29 <annegentle> yeah there are definitely people with info in their heads that we need out of their heads
14:11:39 <annegentle> Sam-I-Am: really? I don't think it's statistically significant?
14:11:46 <AJaeger> I'm not saying we can rest, I think we're all convinced that we can improve
14:11:55 <nickchase> agreed.
14:11:59 <annegentle> yes
14:12:04 <Sam-I-Am> annegentle: i know of a few
14:12:09 <annegentle> so what are some of the solutions?
14:12:34 <AJaeger> we also have to balance whatever we do with the work it puts on us.
14:12:35 <nickchase> Maybe we should have a boilerplate email for first time contributors.  When we do a review...
14:12:38 <annegentle> Sam-I-Am: it's less than 1% I'm sure of all ATC badges
14:12:42 <Sam-I-Am> we're probably the least-encumbered project. you can patch an isolated thing in docs and not go through a whole gating process.
14:12:43 <AJaeger> nickchase, we have already
14:12:45 <annegentle> nickchase: we do
14:12:46 <nickchase> of their first patch, we should maybe send them an email that explains....
14:12:56 <nickchase> what we're doing and why so they don't get freaked out.
14:13:17 <nickchase> I'm not familiar with this initial email.
14:13:18 <Sam-I-Am> there is one, but maybe it could use some updates
14:13:29 <nickchase> Everyone knowing it exists would be good. :)
14:13:46 <Sam-I-Am> AJaeger: do you know what manages it?
14:13:57 <annegentle> nickchase: I'll find one, we've had a lot of new contributors to api docs lately
14:14:07 <AJaeger> Sam-I-Am, some infra magic
14:14:41 <annegentle> #link https://review.openstack.org/#/c/154484/
14:15:03 <annegentle> nickchase: look at the "Welcome, new contributor!" line for the text
14:15:18 <annegentle> "don't be concerned if requested to make corrections"
14:15:30 <annegentle> "be paitent and be available"
14:15:35 <nickchase> yes, I was just looking.
14:15:46 <nickchase> I'm thinking there are definitely some things that could be added.
14:15:47 <AJaeger> The text was written by Tom fifieldt
14:15:56 <fifieldt> hola
14:15:59 <AJaeger> It'S the same text for all projects
14:16:05 <nickchase> Hey, fifeldt
14:16:06 <annegentle> nickchase: yes, just grep for key phrases in the infra repos
14:16:08 <nickchase> aha.
14:16:10 <annegentle> hey fifieldt
14:16:31 <AJaeger> yeah, me summoned fifieldt ;)
14:16:34 * fifieldt tries to catch up with scrollback
14:16:39 <nickchase> ok, so that answers my next question: is this for initial DOCS contributions or for their first contribution period.
14:16:51 <AJaeger> nickchase, first contribution to openstack overall
14:16:55 <annegentle> everyone, all projects
14:17:12 <nickchase> OK, so what I was hoping for was something doc-specific.
14:17:24 <annegentle> nickchase: I'll fight you to keep it "just like code"
14:17:25 <annegentle> :)
14:17:35 <annegentle> nickchase: we really don't want to set up "other" or docs ghetto
14:17:38 <Sam-I-Am> annegentle: just a heads up, the bus internet is flaky :/
14:17:47 <annegentle> nickchase: I feel so strongly about it that I can hardly type enough :)
14:18:04 <nickchase> Well, then I'll go back to my first thought: maybe we need an email that "mentors" can send to first time contributors.
14:18:12 <nickchase> Which is what I was thinking in the first place.
14:18:17 <annegentle> nickchase: I really like the mentoring idea
14:18:27 <annegentle> nickchase: it's more personal than a bot
14:18:33 <fifieldt> btw, if you want a custom "Welcome, new Contributor" just for docs, we can probably do that
14:18:33 <nickchase> exactly
14:19:03 <annegentle> fifieldt: I'd block it, honestly. I feel very strongly that as we go to team's self service we need to not set apart docs from any other type of contribution.
14:19:13 <fifieldt> works for me
14:19:19 <Sam-I-Am> do we want to reach out to people, or tell them to reach out to us if they want to contribute more?
14:19:22 <AJaeger> I'm with annegentle
14:19:24 <annegentle> teams are going to get less and less support from us in the way of reviews anyway
14:19:34 <openstackgerrit> Sayali Lunkad proposed openstack/training-guides: Modifies osbash files to use osbash ssh keys  https://review.openstack.org/158668
14:19:50 <annegentle> but we do have to train reviewers of docs specifically
14:20:09 <annegentle> so I do think we should noodle on what a doc mentoring pairing would be like
14:20:31 <annegentle> I think the specialty teams are one way this is happening already, people are meeting each other due to common knowledge areas
14:20:34 <Sam-I-Am> onboarding for both contributions and reviews makes sense
14:20:44 <AJaeger> there'Re some people that need mentoring - and some just grab it easily ;)
14:21:20 <annegentle> some of the discussion does have to lead to our own agreement on what we review -- content, conventions, technical accuracy
14:21:21 <AJaeger> but even the later ones have questions...
14:21:28 <annegentle> agreed AJaeger
14:21:46 <nickchase> agreed
14:21:47 <annegentle> I also strongly feel that anything that leads to another doc bug being filed is broken.
14:22:00 <annegentle> we have way too many doc bugs and no clear assignees
14:22:02 <nickchase> disagreed :)
14:22:09 <annegentle> nickchase: I know :)
14:22:27 <annegentle> and prioritizing cleanup over content is also problematic for our end goal of providing accurate docs
14:22:58 <nickchase> I'll go back to my original assertion:  if people with the skills for the hard stuff could leave the "monkey work" to someone else there would be fewer of the hard bugs you're worried about.
14:23:02 <nickchase> agreed.
14:23:09 <annegentle> what I see in the API docs is that the patch needs to be very clean because NO ONE will clean it up, two case in points that came up this week are the Firewall aaS and VPN aaS docs.
14:23:25 <annegentle> last updated in 2013, warned since last August they were going away, just yesterday noticed that they were gone.
14:23:33 <fifieldt> I think WADL is quite a different beast to other docs
14:23:38 <annegentle> fifieldt: true that :)
14:23:47 <Sam-I-Am> agreed on that
14:24:03 <nickchase> We NEVER have a surfeit of low-hanging-fruit.
14:24:08 <annegentle> so nickchase I am interested in identifying ways to clean up
14:24:09 <fifieldt> I believe most of what we're talking about here is not api site stuff
14:24:09 <AJaeger> fifieldt, it's the extreme end but shows the problem
14:24:11 <Sam-I-Am> i suspect un-encumbered rst with an easier too chain will reduce some of the overhead for any kind of patch, even fix-ups
14:24:21 <annegentle> and, with the mentoring idea, we WILL need more low hanging fruit
14:24:30 <nickchase> yes.
14:24:35 <openstackgerrit> Merged openstack/api-site: Fix a explain of "Create subnet" Remove following sentence.  https://review.openstack.org/158160
14:24:41 <AJaeger> yeah, setting up maven and getting docbook right is not that trivial
14:25:06 <Sam-I-Am> question is... does non-impactful edits need bugs?
14:25:28 <AJaeger> Sam-I-Am, clear no from my perspective
14:25:28 <taroth> from my perspective: no
14:25:35 <fifieldt> at the moment we track quite a lot of these sorts of things with generic bugs
14:25:38 <fifieldt> like one per book
14:25:47 <Sam-I-Am> yeah, or a bp/spec
14:25:59 <AJaeger> Sam-I-Am, I mean: IF you notice something, no need to open a bug.
14:26:05 <fifieldt> eg https://bugs.launchpad.net/openstack-manuals/+bug/1217503
14:26:06 <openstack> Launchpad bug 1217503 in openstack-manuals "Apply document markup conventions to source XML files" [Wishlist,In progress]
14:26:13 <annegentle> is there a way to have low hanging fruit without bugs?
14:26:22 <AJaeger> Another problem is if you know something is wrong and cannot fix it directly - how to record that?
14:26:27 <annegentle> the bug thing makes me worried
14:26:41 <nickchase> OK, hang on, I have a very basic question:
14:26:54 <AJaeger> annegentle, we can always track it elsewhere - or as part of a single bug.
14:27:15 <Sam-I-Am> annegentle: maybe an ongoing low-hanging-fruit bug that keeps a list of particular places that need attention?
14:27:17 <nickchase> Call me crazy -- and I'm not suggesting that tracking as a single bug is a Bad Thing -- but why (aside from statistics) are more bugs so terrible?
14:27:24 <Sam-I-Am> "first time contributor bug" heh
14:27:44 <annegentle> nickchase: for a few reasons
14:27:55 <annegentle> 1) projects will need to track their own doc bugs in the big tent
14:28:07 <fifieldt> will they?
14:28:13 <fifieldt> :)
14:28:18 <annegentle> 2) bugs for "shared" project docs are already too high with over 500
14:28:42 <annegentle> 3) more bugs means less trust of docs
14:28:51 <annegentle> fifieldt: it remains to be seen :)
14:28:57 <fifieldt> 3 is clearly moot - there are already more bugs in docs than neutron :)
14:29:02 <Sam-I-Am> most of our bugs are these docimpacts people throw over the fence
14:29:06 <fifieldt> so since #1 is still debatable, that leaves #2
14:29:08 <annegentle> ha
14:29:20 <Sam-I-Am> what we need is more of those people contributing
14:29:28 <fifieldt> and #2 can be combated by making a separate launchpad project or (laugh here) a special category on storyboard
14:29:33 <nickchase> Sam-I-Am: agreed
14:29:41 <annegentle> Sam-I-Am: right and the current mailing list discussion of rolling releases doesn't give me hope many will contribute :)
14:29:42 <Sam-I-Am> we're not here to understand the intricacies of all projects. we're here to make the docs usable.
14:29:58 <annegentle> Sam-I-Am: we can also debate "which docs" usable
14:30:13 <annegentle> Sam-I-Am: if we narrow the scope to only what we have now, what might change about our reviews?
14:30:18 * nickchase is feeling bad because after that whole "template" discussion we had in Atlanta he never got it done.
14:30:33 <annegentle> nickchase: no worries, someone else did it right?
14:30:35 <Sam-I-Am> nickchase: we all have our dumpster fires
14:30:44 <annegentle> so another idea
14:30:51 <annegentle> for each deliverable, have smaller review teams
14:30:53 <nickchase> annegentle:  not that I know of
14:31:04 <annegentle> get rid of the central docs-core and have cores on individual books. Go.
14:31:25 <nickchase> how does that help, though?
14:31:33 <annegentle> better yet. -- only track bugs against one deliverable
14:31:40 <fifieldt> does anyone feel like we're starting to mix issues here? "The Way Forward" Big thinking, with a current issue on review narkyness :)
14:31:42 <AJaeger> annegentle, independed of this: let's cleanup docs-core of people that didn't review anything in the last 6 months. We have a few of these AFAIR
14:31:43 <annegentle> then we'll know which ones are the most "in trouble"
14:32:10 <Sam-I-Am> fifieldt: timecube :)
14:32:15 <annegentle> AJaeger: sure, and there are lots of people wanting to be core, but it might be easier for them to become core on a single book at a time
14:32:16 <nickchase> fifieldt:  I don't think so
14:32:21 <KLevenstein> annegentle: books core = more formal version of the "specialty team"?
14:32:50 <fifieldt> it's not a terrible idea
14:32:52 <annegentle> KLevenstein: right. The Security Guide team does this already, where only security team members can actually publish that book.
14:32:55 <AJaeger> annegentle, we can only have cores per repository.
14:33:10 <annegentle> it's a handshake right now, as in, AJaeger and I "know" not to publish their book.
14:33:31 <annegentle> There's also a balancing act between "protection of publish rights" and "speed of change"
14:33:45 <AJaeger> I'm not yet completely convinced that all the special teams do work great...
14:33:52 <AJaeger> Each needs a driving force behind it
14:33:54 <nickchase> ok, so that I feel is off track.
14:33:57 <nickchase> :)
14:33:58 <annegentle> I think that it's part of what nickchase was struggling with though.
14:34:12 <annegentle> nickchase: you can't override a core's decision
14:34:23 <annegentle> or is it the "anyone's -1 blocking"?
14:34:24 <Sam-I-Am> i think each subteam will have their qualms for their specific document
14:34:37 <Sam-I-Am> theres general review guidelines, sure
14:34:41 <nickchase> It's the "anyone's -1 blocking".
14:34:50 <annegentle> many of the suggestions revolve around "don't block, fix"
14:35:01 <annegentle> and the only difficuly I had with one of the "fix" suggestions was log a bug.
14:35:04 <nickchase> that's true.
14:35:14 <annegentle> I guess I can relax a bit and know we'll always have more bugs than the team.
14:35:16 <AJaeger> annegentle, I find it important that we have a shared team - overlapping - so that knowledge gets exchanged. Not every special team should reinvent their own conventions.
14:35:23 <Sam-I-Am> sometimes its easier just to slurp someone's patch and fix it rather than go through a bunch of -1s, especially for new contributors.
14:35:25 <annegentle> AJaeger: very true, that.
14:35:29 <fifieldt> AJaeger, agreed
14:35:39 <fifieldt> and we'll also still have our beloved common directory ;)
14:35:43 <nickchase> AJaeger: agreed
14:35:50 <annegentle> (know we, docs, will have more bugs than individual project teams)
14:36:00 <Sam-I-Am> question is... are the issues bad enough to keep it from being published.
14:36:04 <AJaeger> and anybody can take the patch and fix it. So, if I do a -1 and don't have time to fix it, nickchase can fix the patch up properly.
14:36:20 <nickchase> If it's marked so I can FIND it, sure.
14:36:22 <Sam-I-Am> might be possible to partial-bug something that needs fixups rather than generating a new bug
14:36:29 <Sam-I-Am> then closes-bug once its fixed
14:36:31 <fifieldt> one issue with fixing a patch for a newcomer is ensuring education about what they should do if they subsequently need to update it
14:36:37 <fifieldt> otherwise it can be confusing as hell
14:36:37 <AJaeger> Are we in a hurry to publish patches?
14:36:49 <fifieldt> so probably worth getting some generic text in order for that
14:36:54 <fifieldt> to explain what we've done and why
14:36:59 <fifieldt> and how to update their own repo
14:36:59 <nickchase> OK, so I think fifieldt hits on where we started: communication.
14:37:14 <AJaeger> fifieldt, exactly: So, what I do sometimes: Do a proper review and then mark it as WIP with a note "Let me fix this for you...."
14:37:24 <sld> fifieldt: are you talking about cherrypicking, or simply pulling in updates to re-edit files?
14:37:35 <nickchase> Right.  If you tell someone to update their patch, in general, unless they're really experienced, you will get a blank stare.
14:37:43 <fifieldt> sld: review -d 89789078907; git commit -a; git review
14:37:54 <sld> ah
14:37:58 <AJaeger> I think fifieldt is saying that we should tell them how to fix their patch, we should help them doing the second iteration of it
14:38:06 <nickchase> +1
14:38:07 <fifieldt> no
14:38:16 <fifieldt> what I'm saying is if we are fixing their patch
14:38:22 <fifieldt> we need to explain the process we're taking
14:38:26 <AJaeger> Ah...
14:38:29 <nickchase> +1 on that too. :)
14:38:33 <sld> lol
14:38:43 <Sam-I-Am> explaining is +++
14:38:45 <nickchase> I think either way it's better than what we have now.
14:38:56 <annegentle> #link https://wiki.openstack.org/wiki/Documentation/HowTo#How_to_amend_a_review-in-progress
14:39:02 <fifieldt> just looking for some text that says "hey, there's this stupid thing. I'm going to fix it for you quickly so you don't have to waste your time. This is going to break your local repo, so do this: btw this is what I did"
14:39:06 <annegentle> I've started pasting that into the review when it needs patching
14:39:18 <sld> fifieldt: awesome idea
14:39:32 <annegentle> I'll add to it what to do when someone else patches your patch
14:39:38 <AJaeger> nickchase, I think you're only seeing a few bad examples, there's a lot of good work already happening
14:39:40 <AJaeger> and especially fifieldt'S communication is great
14:39:57 <fifieldt> https://etherpad.openstack.org/p/docs-fixed-it-for-you <-- anyone care to edit
14:40:00 <nickchase> AJaeger: I'm glad, but if people don't know that we have a problem.
14:40:34 <nickchase> So ok, let me recap for a moment, if that's OK...
14:41:20 <nickchase> We agree that we need to do something, and communication seems to be the best answer.  We are crafting a "standard" message that we can give to newbies when we fix their stuff https://etherpad.openstack.org/p/docs-fixed-it-for-you with the idea that ...
14:41:44 <annegentle> the idea that we communicate "this is how we work, welcome!"
14:41:50 <nickchase> it will get things in quickly, not frustrate people, and not tick them off or make them feel stepped on, while still educating them on what it is that they can do better next time.
14:42:01 <annegentle> yes, education is key
14:42:11 <AJaeger> so, when do we fix and when do we just comment?
14:42:24 <Sam-I-Am> one of the things we discussed was how docs makes things look pretty after the actual meat is done. so editing other people's patches should be weird.
14:42:28 <nickchase> I think that's a judgement call on the revieiwer.
14:42:35 <AJaeger> I think a rule of thumb would be if it'S less than 3 edits, fix yourself, if it's more than 10 - let the author do it...
14:42:39 <Sam-I-Am> someone does the hard work of configuring X thing, and we make it pretty.
14:43:01 <nickchase> And there's definite value in that.
14:43:14 <annegentle> dead serious
14:43:15 <nickchase> Are you objecting to ...
14:43:18 <AJaeger> Sam-I-Am, yes, we can do this as well - but that's something we should *arrange* and communicate before
14:43:24 <nickchase> the notion that we clean things up, or the word "pretty"?
14:43:33 <annegentle> we make things consistent and more readable, therefore more usable
14:43:36 <nickchase> (also dead serious)
14:43:42 <nickchase> Ah, so "pretty".
14:44:00 <Sam-I-Am> notion that we know our nitpicky conventions that keep everything presentable and sane
14:44:03 <annegentle> it  might be a "girl" thing but that is the fast track to the docs ghetto.
14:44:27 <annegentle> we know how to make the contribution fit with the rest of the docs, which naturally we are more accustomed to and familiar with
14:44:31 * Sam-I-Am transfer to phoneirc
14:44:38 <KLevenstein> annegentle: fwiw agreed, "pretty" does can an implication of "looks nice, not much there"
14:45:14 <annegentle> right.
14:45:21 <KLevenstein> *can have an; valkyrie needs coffee
14:45:25 <nickchase> annegentle: maybe I'm the weird one, I just think "pretty" in the context of "pretty-print".  But that's probably just me.  Connotations acknowledged.
14:45:32 <annegentle> heh
14:45:49 <nickchase> OK, so let me go back for a moment...
14:45:55 <fifieldt> text @ https://etherpad.openstack.org/p/docs-fixed-it-for-you is a little less informal now for y'all if desired
14:46:03 <nickchase> to "we make things consistent and more readable, therefore more usable" ...
14:46:10 <nickchase> Are you referring to conventions here?
14:46:19 <annegentle> nickchase: yes
14:46:31 <annegentle> nickchase: also better writing, less meandering is easier to read
14:47:10 <nickchase> So you're saying there that WE handle the conventions.
14:47:19 <nickchase> Which is different from making the author handle the conventions.
14:47:28 <nickchase> Also that we fix the "writing"
14:47:39 <nickchase> which is useful when we are trying to get information out of engineer brains.
14:47:44 <nickchase> Which brings me back to...
14:47:55 <Sam-I-Am> in other words, if someone docs a new swift feature, no one here really know the internals of swift, but we can make it conform and presentable like the other docs
14:47:59 <annegentle> nickchase: sometimes. it's a judgement call, which is why I'd like us to train more people on good judgement.
14:48:18 <nickchase> my original assertion: that we should let them focus on the stuff that's only in their brains.
14:48:21 <Sam-I-Am> with rst i think well get a lot more "engineer" contribs
14:48:36 <nickchase> I agree, which is why it's REALLY important that...
14:48:37 <annegentle> Sam-I-Am: that's the hope, and swift already does all their docs in rst really
14:48:48 <nickchase> we use this opportunity to encourage those people and not drive them away.
14:48:49 <AJaeger> nickchase, we can do this in special cases - but not for each and every patch
14:48:55 <annegentle> but with RST we will still have markup conventions
14:49:09 <Sam-I-Am> swift was a bad example
14:49:24 <Sam-I-Am> i hope our rst isnt as cumbersome
14:49:25 <fifieldt> bottom line: we want every review on every patch to be encouraging that patch submitted to become the #1 docs contributor
14:49:34 <Sam-I-Am> rst is designed to be light
14:49:38 <fifieldt> s/submitted/submitter/
14:50:04 <sld> fifieldt: i like that ideology / concept. :)
14:50:09 <nickchase> fifieldt: it sounds sappy, but, well, yeah.
14:50:12 <sld> the more someone is encouraged, the more they contribute.
14:50:35 <Sam-I-Am> the more they dont have to waste time on nits
14:50:38 <nickchase> I have a suggestion:
14:50:43 <berendt> what about an easy and light step-by-step guide "how to commit to openstack documentation in 10 minutes"? At the moment we link to https://wiki.openstack.org/wiki/Documentation/HowTo on http://docs.openstack.org/. This is a complex and long document and as a first time contributor I do not know if i have to read the whole document, what are the relevant parts, and so on.
14:50:57 <annegentle> berendt: it is long, isn't it?
14:51:00 <fifieldt> https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers
14:51:04 <fifieldt> something like that?
14:51:09 <sld> yeah
14:51:10 <nickchase> Unfortunately, there are a LOT of steps that are actually necessary.
14:51:14 <nickchase> but
14:51:14 <Sam-I-Am> berendt: our conventions are a mile long too
14:51:23 <AJaeger> There's also http://docs.openstack.org/infra/manual/
14:51:33 <fifieldt> random idea:
14:51:42 <fifieldt> hmm
14:51:43 <fifieldt> maybe not
14:51:44 <AJaeger> not doc specific - but the new generic information for OpenStack contribution
14:52:18 <nickchase> OK, I have a potential compromise:
14:52:54 <nickchase> We want people to not be frustrated or bogged down, but we don't want a preponderance of new bugs.  One way to do that would be ...
14:53:04 <berendt> I think there should be a light document for a first time contributor making it really easy to push a first commit. I do not think that any new contributor reads the linked document before the first commit.
14:53:37 <nickchase> If we institute a policy that if you see something simple, it's OK to just fix it with the text in https://etherpad.openstack.org/p/docs-fixed-it-for-you . If it's more complicated....
14:53:45 <AJaeger> During reviews, I often link to special sections of the conventions
14:54:06 <sld> AJaeger: +1 - it's been immensely helpful, too. :)
14:54:12 <annegentle> AJaeger: me too
14:54:24 <annegentle> nickchase: yep, I think that's the way.
14:54:36 <nickchase> then we tell the author that this is what it needs, but if they are willing to file a new bug and paste the URL in the comments, then we can close this one.  (I'm assuming these are non-impactful) bugs.  The hassle of filing a new bug...
14:54:45 <AJaeger> and I even got this week a comment: I would have loved to know about the markup conventions before I did my first patch..
14:55:07 <annegentle> AJaeger: yeah! from Robin I think?
14:55:12 <nickchase> will discourage most people and encourage them to do the right thing and just do the fix, but in extreme cases we will have a smaller number of new bugs that a first-timer can patch.
14:55:26 <annegentle> great summary
14:55:27 <nickchase> Would that be OK?
14:55:31 <KLevenstein> so, in fact—I wrote a lightweight “how to contribute to openstack” doc for my team at rackspace to try and simplify what’s at the main page. would be happy to share it.
14:55:36 <AJaeger> annegentle, don't remember who it was
14:55:44 <berendt> KLevenstein: cool
14:55:48 <taroth> KLevenstein: great
14:55:50 <annegentle> KLevenstein: cool
14:55:58 <annegentle> sorry we'd better get to the other topics!
14:56:00 <nickchase> KLevenstein: definitely
14:56:05 <KLevenstein> I don’t know how much simpler it actually is, but.
14:56:07 <nickchase> OK, so do we agree on this, then?
14:56:17 <AJaeger> KLevenstein, let's share and look
14:56:17 <annegentle> Yes.
14:56:18 <openstackgerrit> Merged openstack/openstack-manuals: Update CLI reference for python-openstackclient 1.0.2  https://review.openstack.org/159452
14:56:21 <nickchase> EXCELLENT.
14:56:42 <annegentle> #agreed institute a policy that if you see something simple, it's OK to just fix it with the text in https://etherpad.openstack.org/p/docs-fixed-it-for-you
14:56:45 <Sam-I-Am> rst toolchain should make it lighter
14:57:09 <annegentle> KLevenstein: do you want an action item to share that?
14:57:18 <KLevenstein> annegentle: sure
14:57:34 <annegentle> #action KLevenstein to share a lightweight “how to contribute to openstack” doc
14:57:38 <annegentle> Okay
14:58:04 <annegentle> not sure I need another agreed statement on the more complex policies?
14:58:07 <annegentle> Something like
14:58:24 <openstackgerrit> Merged openstack/openstack-manuals: Update CLI reference for python-cinderclient 1.1.1  https://review.openstack.org/159435
14:58:38 <annegentle> #agreed for balancing a contributor's frustration level with publishing ease, please use good judgement and seek out guidance
14:58:59 <annegentle> Okay better get to User Guides new specialty team
14:59:03 <nickchase> annegentle:  sorry to be nitpicky, but I don't see the part about enabling a person to get a bug closed by filing a new one if they're motivated to do that.
14:59:11 <annegentle> #topic User Guides new specialty team
14:59:15 <nickchase> If that's implicit, fine.
14:59:25 <annegentle> nickchase: that was complex to me :)
14:59:46 <annegentle> nickchase: and a judgement call
14:59:59 <nickchase> ok, let's move on.  I'll post a proposed statement to the list.
15:00:03 <annegentle> ok thanks
15:00:19 <annegentle> taroth: thanks for joining us, sorry we didn't get to the User Guide for long
15:00:26 <taroth> annegentle: np
15:00:34 <annegentle> taroth: and I do owe you an email back on your excellent questions about the user guide and admin guide
15:00:40 <annegentle> also
15:00:48 <annegentle> #topic Installation Guides split for Kilo
15:00:54 <annegentle> we no longer publish install guides to /trunk/
15:01:04 <annegentle> and it is open to kilo now, right Sam-I-Am?
15:01:16 <annegentle> heh no one else has to use this meeting room bwah hah ha
15:01:18 <AJaeger> annegentle, did you remove /trunk/install-guides and /trunk/training-guides as well?
15:01:30 <nickchase> :)
15:01:32 <AJaeger> we should announce that it's open
15:02:04 <sld> AJaeger: remove = .htaccess or actual filesystem file removal .. or both?
15:02:18 <sld> err .htaccess redirects
15:02:21 <annegentle> AJaeger: oh I can do that today since I'm home
15:02:33 <AJaeger> sld, rm -rf docs.openstack.org/trunk/{install-guide,training-guides} - and add proper redirects
15:02:39 <sld> ah
15:02:41 <fifieldt> the magical password that only exists on Anne's PC at home :D
15:02:50 <annegentle> fifieldt: actually it's about the network
15:02:53 <AJaeger> fifieldt, the one she wanted to share? ;)
15:02:56 <fifieldt> oh, right, I see :)
15:03:07 <fifieldt> I'm just having vague recollections
15:03:12 <annegentle> fifieldt: I sorted the other by phoning infra :)
15:03:13 <fifieldt> of amusement
15:03:22 <fifieldt> Who you gonna call :)
15:03:27 <annegentle> ghostbusters!
15:03:36 <sld> annegentle: that's my line! lol
15:03:50 <AJaeger> sld, that was the password ;)
15:03:51 <taroth> :)
15:03:53 <annegentle> Okay, I did want to bring up https://review.openstack.org/#/c/157303/ since there's a concern this merged too fast
15:04:06 <annegentle> it wasn't tested, and doesn't tell the user to change the API version
15:04:31 <annegentle> it's fairly safe since it's not published, though, but, this is where "it's a judgement call" comes in -- did anyone log a bug about it?
15:04:43 <annegentle> Sam-I-Am: you noticed it, can you log a bug for investigation?
15:05:01 <fifieldt> is trunk still broken for cinderclient, Sam-I-Am?
15:05:21 <annegentle> he's on his phone so might have difficulty, I'll follow up and let us end the meeting!
15:05:34 <nickchase> thanks everyone!
15:05:37 <AJaeger> can we talk about the driver docs spec?
15:05:39 <AJaeger> https://review.openstack.org/#/c/133372/
15:05:39 <annegentle> The doc tools update is on the mailing list too, so that's all for now
15:05:48 <annegentle> AJaeger: oh yes. What are your thoughts now?
15:06:01 * AJaeger likes to hand over the spec to somebody else...
15:06:26 <openstackgerrit> Merged openstack/openstack-manuals: Update CLI reference for python-ceilometerclient 1.0.13  https://review.openstack.org/159434
15:06:29 <AJaeger> fifieldt raised a point during review that we might have good documentation that won't be that easy to move to vendor docs.
15:06:57 <annegentle> I am frankly surprised at how little vendor doc there is on _their_ sites
15:07:03 <annegentle> it's like we made TOO good a docs site. ha.
15:07:06 <AJaeger> I was thinking whether we should make "maintenance" of the doc a requirement
15:07:19 <berendt> AJaeger: +1
15:07:19 <annegentle> So I'm feeling a little like our proposed solution wouldn't work anyway, to link to vendor sites.
15:07:20 <AJaeger> So, either they do a minimal spec that needs no maintenance
15:07:35 <annegentle> #topic Driver docs spec
15:07:41 <AJaeger> Or if they want something more flashed on our side, we need one contact person and an update for each release...
15:08:15 <AJaeger> and if nothing happens and the content is outdated, we revert it to the minimal doc
15:08:20 <annegentle> I feel like we already have a carrot, a great docs site that many people just use as "the place" to find out how to use a driver.
15:08:20 <berendt> we should also note that we will remove content if the contact person is not responsive and if there is no update after a release
15:08:29 <annegentle> so the stick is removing the content, right?
15:08:41 <AJaeger> annegentle, yep
15:09:04 <annegentle> AJaeger: ok so is the spec saying that currently? I don't recall
15:09:20 <AJaeger> No, it'S not - the spec currently says we will have minimal doc for everything.
15:09:24 <annegentle> AJaeger: I think the spec has been very valuable to find out the facts.
15:09:30 <fifieldt> +1
15:09:33 <annegentle> AJaeger: and has done its job of finding a good solution.
15:09:41 <AJaeger> But seeing the recent feedback, I'm considering changing it.
15:09:43 <annegentle> AJaeger: thanks so much for doing the work of discovery
15:09:47 <annegentle> AJaeger: yes, I agree
15:09:50 <AJaeger> And the stick is one approach ;)
15:09:59 <annegentle> I think we found out important aspects that gave us both carrot and stick :)
15:09:59 <AJaeger> If anybody has a better one, please tell.
15:10:14 <fifieldt> sounds like AJaeger has things under control as usual :)
15:10:19 <annegentle> what sucks, honeslty, is that even teh stick creates work
15:10:28 <annegentle> it's maddening
15:10:32 <AJaeger> fifieldt, this has been going on for far too long for me ;(
15:10:37 <fifieldt> absolutely
15:10:41 <annegentle> AJaeger: yeah let's get resolution
15:10:54 <AJaeger> What about the following plan:
15:10:55 <fifieldt> sorry for the lengthy reply times, but I think this is quite important to do right
15:11:02 <AJaeger> action for me to update the spec
15:11:31 <AJaeger> We review quickly and annegentle makes a last call in her weekly doc status mail
15:11:39 <annegentle> sounds good
15:11:44 <AJaeger> and next wednesday it gets approved
15:11:49 <fifieldt> works for me
15:12:03 <annegentle> #action AJaeger to update the docs driver spec at https://review.openstack.org/#/c/133372/
15:12:23 * Sam-I-Am has internet again
15:12:27 <annegentle> #action annegentle to make a call for final review in the weekly docs status update post
15:12:31 <AJaeger> WElcome back, Sam-I-Am !
15:12:54 <annegentle> Sam-I-Am: great! Was just asking if you had logged a doc bug for the cinder client testing for the install guide to close that loop.
15:13:27 <annegentle> #action annegentle to update .htaccess and then delete /trunk/install and /trunk/training-guides
15:13:33 <annegentle> I think that's it
15:13:41 <annegentle> thanks all for joining and going over, sorry about that.
15:13:42 <Sam-I-Am> annegentle: no, i havent..
15:13:48 <AJaeger> annegentle, also check the index pages for any mention fo these
15:13:55 <Sam-I-Am> annegentle: i think we'll be trying the openstack client for kilo... it might work better :)
15:13:57 <annegentle> AJaeger: got it
15:14:05 <AJaeger> thanks, annegentle !
15:14:18 <annegentle> #endmeeting