<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On 3 March 2016 at 18:35, Stephen Balukoff <span dir="ltr"><<a href="mailto:sbalukoff@bluebox.net" target="_blank">sbalukoff@bluebox.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">Hi Armando,<div><br></div><div>Please rest assured that I really am a fan of requiring. I realize that sarcasm doesn't translate to text, so you'll have to trust me when I say that I am not being sarcastic by saying that.</div><div><br></div><div>However, I am not a fan of being given nebulous requirements and then being accused of laziness or neglect when I ask for help. More on that later. </div></div></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><br></div><div>Also, the intent of my e-mail wasn't to call you out and I think you are right to require that new features be documented. I would do the same in your position.</div><div class="gmail_extra"><br><div class="gmail_quote"><span class=""><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>To start off, my humble suggestion would be to be kind and provide a TL;DR before going in such depth, otherwise there's a danger of missing the opportunity to reach out the right audience. I read this far because I felt I was called into question (after all I am the one 'imposing' the documentation requirement on the features we are delivering in Mitaka)!</div></div></div></div></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div><div>That said, If you are a seasoned LBaaS developer and you don't know where LBaaS doc is located or how to contribute, that tells me that LBaaS docs are chronically neglected, and the links below are a proof of my fear.</div></div></div></div></blockquote><div><br></div></span><div>Yes, obviously. I am not interested in shoveling out blame. I'm interested in solutions to the problem.</div><div><br></div><div>Also, how is telling us "wow, your documentation sucks" in any way helpful in an e-mail thread where I'm asking, essentially, "How do I go about fixing the documentation?"  If nothing else, it should provide evidence that there is a problem (which I am trying to point out in this e-mail thread!)</div><span class=""><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">In a nutshell, this is a rather disastrous. Other Neutron developers already contribute successfully to user docs [5]. Most of it is already converted to rst and the tools you're familiar with are the ones used to produce content (like specs).</div></div></div></blockquote><div><br></div></span><div>Really? Which tools? tox? Are there templates somewhere? (I know there are spec templates... but what about openstack manual templates?)  If there are templates, where are they? Also, evidence that others are making contributions to the manual is not necessarily evidence that they're doing it correctly or consistently.</div><div><br></div><div>You're referring to what is essentially tribal knowledge. This is not a good way to proceed if you want things to be consistent and done the best way.</div><div><br></div><div>I have been doing this for a while (obviously not as long as some), and I've seen it done in many different ways in different projects. Where are the usable best practices guides?</div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">My suggestion would be to forge your own path, and identify a place in the networking-guide where to locate some relevant content that describe LBaaS/Octavia: deployment architecture, features, etc. This is a long journey, that requires help from all parties, but I believe that the initiative needs to be driven from the LBaaS team as they are the custodian of the knowledge.</div><div class="gmail_quote"><br></div></div></div></blockquote><div><br></div></span><div>Again, the "figure it out" approach means you are going to get inconsistent results (like the current poor documentation that you linked). What I'm asking for in this e-mail is a guide on how it *should* be done that is consistent across OpenStack, that is actually consumable without having to read the whole of the OpenStack manual cover-to-cover. This needs to not be tribal knowledge if we are going to hold people accountable for not complying with an unwritten standard.</div><div><br></div><div>You're not seeing a lack of initiative. Heck, the Neutron-LBaaS and Octavia projects have some of the most productive people working on them that I've seen anywhere. You're seeing lack of meaningful guidance, and lack of standards.</div><span class=""><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"></div><div class="gmail_quote">I fear that if none of the LBaaS core members steps up and figure this out, LBaaS will continue to be something everyone would like to adopt but no-one knows how to, at least not by tapping directly at the open source faucet.</div></div></div></blockquote><div><br></div></span><div>Exactly what I fear as well. Please note that it is offensive to accuse a team of not stepping up when what I am doing in this very e-mail should be pretty good evidence that we are trying to step up.</div></div></div></div></blockquote><div><br></div><div>There's no reason to be offended.</div><div><br></div><div>Rest assured that I have no interest on laying blame on anyone, that's not how one get positive results. I commend your desire to see this done consistently, and I agree that we lack exhaustive documentation to produce documentation! I was simply expressing the fear that the lack of guidance and standards as you point out may end up deterring people from covering an area (LBaaS documentation) that is in desperate need of attention, today. To the risk of leading to the same ill effects I'd rather have inconsistent documentation than no documentation at all, but that's just my opinion with which you don't have to agree with.</div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><span class=""><font color="#888888"><div><br></div><div>Stephen</div></font></span></div><span class=""><div><br></div>-- <br><div><div dir="ltr"><div><div dir="ltr"><div><span></span><div>Stephen Balukoff</div><div>Principal Technologist</div><div>Blue Box, An IBM Company</div><div><a href="http://www.blueboxcloud.com" target="_blank">www.blueboxcloud.com</a></div><div><a href="mailto:sbalukoff@blueboxcloud.com" target="_blank">sbalukoff@blueboxcloud.com</a></div><div><a href="tel:206-607-0660%20x807" value="+12066070660" target="_blank">206-607-0660 x807</a></div></div></div></div></div></div>
</span></div></div>
<br>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>