On 4/6/20 13:03, Donny Davis wrote:
On Mon, Apr 6, 2020 at 3:49 PM melanie witt <melwittt@gmail.com <mailto:melwittt@gmail.com>> wrote:
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> > <mailto: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> <mailto: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.
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"