Re: [openstack-dev] [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Armando M.]

On 3 March 2016 at 18:35, Stephen Balukoff  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
> sbaluk...@blueboxcloud.com
> 

Re: [openstack-dev] [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Stephen Balukoff]

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
sbaluk...@blueboxcloud.com
206-607-0660 x807
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Armando M.]

On 3 March 2016 at 16:56, Stephen Balukoff  wrote:

> Hello!
>
> I have a problem I'm hoping someone can help with: I have gone through the
> task of completing a shiny new feature for an openstack project, and now
> I'm trying to figure out how to get that last all-important documentation
> step done so that people will know about this new feature and use it. But
> I'm having no luck figuring out how I actually go about doing this...
>
> This started when I was told that in order to consider the feature
> "complete," I needed to make sure that it was documented in the openstack
> official documentation. I wholeheartedly agree with this: If it's not
> documented, very few people will know about it, let alone use it. And few
> things make an open-source contributor more sad than the idea that the work
> they've spent months or years completing isn't getting used.
>
> So... No problem! I'm an experienced OpenStack developer, and I just spent
> months getting this major new feature through my project's gauntlet of an
> approval process. How hard could documenting it be, right?
>
> So in the intervening days I've been going through the openstack-manuals,
> openstack-doc-tools, and other repositories, trying to figure out where I
> make my edits. I found both the CLI and API reference in the
> openstack-manuals repository... but when I went to edit these files, I
> noticed that there's a comment at the top stating they are auto-generated
> and shouldn't be edited? It seemed odd to me that the results of something
> auto-generated should be checked into a git repository instead of the
> configuration which creates the auto-generated output... but it's not my
> project, right?
>
> Anyway, so then I went to try to figure out how I get this auto-generated
> output updated, and haven't found much (ha!) documented on the process...
> when I sought help from Sam-I-Am, I was told that these essentially get
> generated once per release by "somebody." So...  I'm done, right?
>
> Well... I'm not so sure. Yes, if the CLI and API documentation gets
> auto-generated from the right sources, we should be good to go on that
> front, but how can I be sure the automated process is pulling this
> information from the right place? Shouldn't there be some kind of
> continuous integration or jenkins check which tests this that I can look
> at? (And if such a thing exists, how am I supposed to find out about it?)
>
> Also, the new feature I've added is somewhat involved, and it could
> probably use another document describing its intended use beyond the CLI /
> API ref. Heck, we already created on in the OpenStack wiki... but I'm also
> being told that we're trying to not rely on the wiki as much, per se, and
> that anything in the wiki really ought to be moved into the "official"
> documentation canon.
>
> So I'm at a loss. I'm a big fan of documentation as a communication
> tool, and I'm an experienced OpenStack developer, but when I look in the
> manual for how to contribute to the OpenStack documentation, I find a guide
> that wants to walk me through setting up gerrit... and very little targeted
> toward someone who already knows that, but just needs to know the actual
> process for updating the manual (and which part of the manual should be
> updated).
>
> When I went back to Sam-I-Am about this, this spawned a much larger
> discussion and he suggested I bring this up on the mailing list because
> there might be some "big picture" issues at play that should get a larger
> discussion. So... here I am.
>
> Here's what I think the problem is:
>
> * We want developers to document the features they add or modify
> * We want developers to provide good user, operator, etc. documentation
> that actual users, operators, etc. can use to understand and use the
> software we're writing.
> * We even go so far as to say that a feature is not complete unless it has
> this documentation (which I agree with)
>

If you agree with this, why do you bring it up twice? :)


> * With a rather small openstack-docs contributor team, we want to automate
> as much as possible, and rely on the docs team to *edit* documentation
> written by developers instead of writing the docs themselves (which is more
> time consuming for the docs team to do, and may miss important things only
> the developers know about.)
>
> But:
>
> * We don't actually provide much help to the developers to know how to do
> this. We have plenty for people who are new to OpenStack to get started
> with gerrit--  but there doesn't seem to be much practical help on where to
> get started, as an experienced contributor to other projects, on the actual
> task of updating the manual.
>
> And I would wager:
>
> * We don't seem to have many automated tools that tie into the jenkins
> gate checks to make sure that new features are properly documented.
> * We need something better than the 'APIImpact' and 'DocImpact' flags you
> can add to a commit message which