Open Stack

On 3 March 2016 at 18:35, Stephen Balukoff <sbalukoff at bluebox.net> wrote:

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

There's no reason to be offended.

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.


>
> Stephen
>
> --
> Stephen Balukoff
> Principal Technologist
> Blue Box, An IBM Company
> www.blueboxcloud.com
> sbalukoff at blueboxcloud.com
> 206-607-0660 x807
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160303/911bf211/attachment.html>