Open Stack

On 4/6/20 13:03, Donny Davis wrote:
> 
> 
> On Mon, Apr 6, 2020 at 3:49 PM melanie witt <melwittt at gmail.com 
> <mailto:melwittt at gmail.com>> wrote:
> 
>     On 4/6/20 08:36, Donny Davis wrote:
>      > On Mon, Apr 6, 2020 at 11:22 AM Artom Lifshitz
>     <alifshit at redhat.com <mailto:alifshit at redhat.com>
>      > <mailto:alifshit at redhat.com <mailto:alifshit at redhat.com>>> wrote:
>      >
>      >     On Sat, Apr 4, 2020 at 9:12 PM Ghanshyam Mann
>      >     <gmann at ghanshyammann.com <mailto:gmann at ghanshyammann.com>
>     <mailto:gmann at ghanshyammann.com <mailto:gmann at 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.
> 
> I have had a couple conversations about trying to put together "docs for 
> mere mortals", but it comes down to time and the right place for it to go.
> I understand we as a community are not really supposed to have an 
> "opinion" on how to best put together a cloud, but maybe it's time we take
> the collective wisdom from those who know what works and what doesn't... 
> and put something together for all of us normal people out there.

To be clear, I don't think we have different opinions about how to best 
put together a cloud. When I say different opinions I mean different 
opinions about how to organize the doc pages, how much verbosity to have 
in the content, that sort of thing.

I have a personal opinion that being too verbose and detailed in the 
"main" content page for a concept can make it needlessly hard to 
understand and not end up helping the reader. In a case like that I'd 
prefer "main" content to be very concise and then have a link to all the 
gory details if someone wants to read that as well.

Sorry if I made it sound like we differ in opinion about how to put 
together the cloud.

-melanie

> I am just a simple human, and I do not think I am alone. This is not 
> meant to be a "our docs suck and we need to refactor them all"... it's 
> more so
> a "we have the content and the wisdom, so let's build something that 
> someone can put in prod and stand on it."
> 
>  From my perspective this has literally been our barrier to adoption.
> -- 
> ~/DonnyD
> C: 805 814 6800
> "No mission too difficult. No sacrifice too great. Duty First"