On 4/6/20 08:36, Donny Davis wrote:
> On Mon, Apr 6, 2020 at 11:22 AM Artom Lifshitz <alifshit@redhat.com
> <mailto:alifshit@redhat.com>> wrote:
>
>     On Sat, Apr 4, 2020 at 9:12 PM Ghanshyam Mann
>     <gmann@ghanshyammann.com <mailto:gmann@ghanshyammann.com>> wrote:
>      >
>      > This topic is a very important and critical area to solve in the
>     OpenStack community.
>      > I personally feel and keep raising this issue wherever I get the
>     opportunity.
>      >
>      > To develop or maintain any software, the very first thing we need
>     is to have enough developer resources.
>      > Without enough developers (either open or closed source), none of
>     the software can survive.
>      >
>      > OpenStack current situation on contributors is not the same as it
>     was few years back.  Almost every
>      > project is facing the less contributor issue as compare to
>     requirements and incoming requests. Few
>      > projects already dead or going to be if we do not solve the less
>     contributors issue now.
>      >
>      > I know, TC is not directly responsible to solve this issue but we
>     should do something or at least find
>      > the way who can solve this.
>
>     I'm not running for TC, but I figured I could chime in with some
>     thoughts, and maybe get TC candidates to react.
>
>      > What do you think about what role TC can play to solve this? What
>     platform or entity can be used by TC to
>      > raise this issue? or any new crazy Idea?
>
>     To my knowledge, the vast majority of contributors to OpenStack are
>     corporate contributors - meaning, they contribute to the community
>     because it's their job. As companies have dropped out, the contributor
>     count has diminished. Therefore, the obvious solution to the
>     contributor dearth would be to recruit new companies that use or sell
>     OpenStack. However, as far as I know, Red Hat is the only company
>     remaining that still makes money from selling OpenStack as a product.
>     So if we're looking for new contributor companies, we would have to
>     look to those that use OpenStack, and try to make the case that it
>     makes sense for them to get involved in the community. I'm not sure
>     what this kind of advocacy would look like, or towards which
>     companies, or what kind of companies, it would be directed. Perhaps
>     the TC candidates could have suggestions here. And if I've made any
>     wrong assumptions, by all means correct me.
>
> I don't think you are too far off.  I used to work in a place where my
> job was to help sell Openstack (among other products) and
> enable the use of it with customers.
>
> Customers drive everything vendors do. Things that sell are easy to use.
> Customers don't buy the best products, they buy what they
> can understand fastest. If customers are asking for a product, it's
> because they understand its value. Vendors in turn contribute
> to projects because they make money from their investment.
>
> Now think about the perception and reality of Openstack as a whole. We
> have spent the last decade or so writing bleeding edge features.
> We have spent very little time on documenting what we do have in
> layman's terms. The intended audience of our docs would seem
> to me to be other developers. I hope people don't take that as a jab,
> it's just the truth. If someone cannot understand how to use
> this amazing technology, it won't sell. If it doesn't sell, vendors
> leave, if vendors leave the number of contributors goes down.
>
> If we don't start working at making Openstack easier to consume, then no
> amount of technical change will make an impactful difference.

I'm not running for the TC either but wanted say Donny's reply here
resonates with me. When I first started working on OpenStack, I was at
Yahoo (now Verizon Media), a company who consumes OpenStack and depends
on it for a (now) large portion of their infrastructure.

At the time I joined the OpenStack community in 2012, the docs about
contributing and the docs about each component were dead simple. I was
up and running in under a day and started my first contributions
upstream shortly after.

Fast forward to now, I find the docs are hard to read and navigate.
There's not much layman's terms. And most of all, at least in Nova, is
that the docs are in dire need of being organized. They used to be
simple but when docs moved in-tree things were hastily cobbled together
because as you mentioned, we're always already stretched trying to
deliver bleeding edge features.

And, there are also differences in opinion about how docs should be
organized and how verbose they are. I have seen docs evolve from simple
to complicated because for example: someone thought they were making an
improvement, whereas I might think they were making the docs less
usable. I'm not aware that there is any guideline or reference
documentation that is to be used as a design goal. Such as, "this is
what your landing page should look like", "here's how docs should be
organized", "you should have these sections", etc.

Sometimes I have thought about proposing a bunch of changes to how our
docs are organized. But, full disclosure, I worry that if I do that and
if it gets accepted/merged, someone else will completely change all of
it later and then all the organization and work I did goes out the
window. And I think this worry highlights the fact that there is no
"right way" of doing the docs. It's just opinion and everyone has a
different opinion.

I'm not sure whether that's solvable. I mentioned a guideline or design
goal to aspire to, but at the same time, we don't want to be so rigid
that projects can't do docs the way they want. So then what? Per project
design goals and guidelines I guess? Or is that too much process? I have
wondered how other communities have managed success in the docs department.

So, back to the contributors point. I was lucky because by the time docs
got hard to consume, I already knew the ropes. I don't know how hard it
has been for newer contributors to join since then and how much of the
difficulty is related to docs.

I'm not sure I've said anything useful, so apologies for derailing the
discussion if I've done that.

-melanie