Open Stack

Hi Armando,

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.

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.

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.

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)!
>

> 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.
>

Yes, obviously. I am not interested in shoveling out blame. I'm interested
in solutions to the problem.

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!)

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).
>

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.

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.

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?


> 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.
>
>
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.

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.

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.
>

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.

Stephen

-- 
Stephen Balukoff
Principal Technologist
Blue Box, An IBM Company
www.blueboxcloud.com
sbalukoff at blueboxcloud.com
206-607-0660 x807
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160303/dc42aa85/attachment.html>