<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Apr 6, 2020 at 3:49 PM melanie witt <<a href="mailto:melwittt@gmail.com">melwittt@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 4/6/20 08:36, Donny Davis wrote:<br>
> On Mon, Apr 6, 2020 at 11:22 AM Artom Lifshitz <<a href="mailto:alifshit@redhat.com" target="_blank">alifshit@redhat.com</a> <br>
> <mailto:<a href="mailto:alifshit@redhat.com" target="_blank">alifshit@redhat.com</a>>> wrote:<br>
> <br>
> On Sat, Apr 4, 2020 at 9:12 PM Ghanshyam Mann<br>
> <<a href="mailto:gmann@ghanshyammann.com" target="_blank">gmann@ghanshyammann.com</a> <mailto:<a href="mailto:gmann@ghanshyammann.com" target="_blank">gmann@ghanshyammann.com</a>>> wrote:<br>
> ><br>
> > This topic is a very important and critical area to solve in the<br>
> OpenStack community.<br>
> > I personally feel and keep raising this issue wherever I get the<br>
> opportunity.<br>
> ><br>
> > To develop or maintain any software, the very first thing we need<br>
> is to have enough developer resources.<br>
> > Without enough developers (either open or closed source), none of<br>
> the software can survive.<br>
> ><br>
> > OpenStack current situation on contributors is not the same as it<br>
> was few years back. Almost every<br>
> > project is facing the less contributor issue as compare to<br>
> requirements and incoming requests. Few<br>
> > projects already dead or going to be if we do not solve the less<br>
> contributors issue now.<br>
> ><br>
> > I know, TC is not directly responsible to solve this issue but we<br>
> should do something or at least find<br>
> > the way who can solve this.<br>
> <br>
> I'm not running for TC, but I figured I could chime in with some<br>
> thoughts, and maybe get TC candidates to react.<br>
> <br>
> > What do you think about what role TC can play to solve this? What<br>
> platform or entity can be used by TC to<br>
> > raise this issue? or any new crazy Idea?<br>
> <br>
> To my knowledge, the vast majority of contributors to OpenStack are<br>
> corporate contributors - meaning, they contribute to the community<br>
> because it's their job. As companies have dropped out, the contributor<br>
> count has diminished. Therefore, the obvious solution to the<br>
> contributor dearth would be to recruit new companies that use or sell<br>
> OpenStack. However, as far as I know, Red Hat is the only company<br>
> remaining that still makes money from selling OpenStack as a product.<br>
> So if we're looking for new contributor companies, we would have to<br>
> look to those that use OpenStack, and try to make the case that it<br>
> makes sense for them to get involved in the community. I'm not sure<br>
> what this kind of advocacy would look like, or towards which<br>
> companies, or what kind of companies, it would be directed. Perhaps<br>
> the TC candidates could have suggestions here. And if I've made any<br>
> wrong assumptions, by all means correct me.<br>
> <br>
> I don't think you are too far off. I used to work in a place where my <br>
> job was to help sell Openstack (among other products) and<br>
> enable the use of it with customers.<br>
> <br>
> Customers drive everything vendors do. Things that sell are easy to use. <br>
> Customers don't buy the best products, they buy what they<br>
> can understand fastest. If customers are asking for a product, it's <br>
> because they understand its value. Vendors in turn contribute<br>
> to projects because they make money from their investment.<br>
> <br>
> Now think about the perception and reality of Openstack as a whole. We <br>
> have spent the last decade or so writing bleeding edge features.<br>
> We have spent very little time on documenting what we do have in <br>
> layman's terms. The intended audience of our docs would seem<br>
> to me to be other developers. I hope people don't take that as a jab, <br>
> it's just the truth. If someone cannot understand how to use<br>
> this amazing technology, it won't sell. If it doesn't sell, vendors <br>
> leave, if vendors leave the number of contributors goes down.<br>
> <br>
> If we don't start working at making Openstack easier to consume, then no <br>
> amount of technical change will make an impactful difference.<br>
<br>
I'm not running for the TC either but wanted say Donny's reply here <br>
resonates with me. When I first started working on OpenStack, I was at <br>
Yahoo (now Verizon Media), a company who consumes OpenStack and depends <br>
on it for a (now) large portion of their infrastructure.<br>
<br>
At the time I joined the OpenStack community in 2012, the docs about <br>
contributing and the docs about each component were dead simple. I was <br>
up and running in under a day and started my first contributions <br>
upstream shortly after.<br>
<br>
Fast forward to now, I find the docs are hard to read and navigate. <br>
There's not much layman's terms. And most of all, at least in Nova, is <br>
that the docs are in dire need of being organized. They used to be <br>
simple but when docs moved in-tree things were hastily cobbled together <br>
because as you mentioned, we're always already stretched trying to <br>
deliver bleeding edge features.<br>
<br>
And, there are also differences in opinion about how docs should be <br>
organized and how verbose they are. I have seen docs evolve from simple <br>
to complicated because for example: someone thought they were making an <br>
improvement, whereas I might think they were making the docs less <br>
usable. I'm not aware that there is any guideline or reference <br>
documentation that is to be used as a design goal. Such as, "this is <br>
what your landing page should look like", "here's how docs should be <br>
organized", "you should have these sections", etc.<br>
<br>
Sometimes I have thought about proposing a bunch of changes to how our <br>
docs are organized. But, full disclosure, I worry that if I do that and <br>
if it gets accepted/merged, someone else will completely change all of <br>
it later and then all the organization and work I did goes out the <br>
window. And I think this worry highlights the fact that there is no <br>
"right way" of doing the docs. It's just opinion and everyone has a <br>
different opinion.<br>
<br>
I'm not sure whether that's solvable. I mentioned a guideline or design <br>
goal to aspire to, but at the same time, we don't want to be so rigid <br>
that projects can't do docs the way they want. So then what? Per project <br>
design goals and guidelines I guess? Or is that too much process? I have <br>
wondered how other communities have managed success in the docs department.<br>
<br>
So, back to the contributors point. I was lucky because by the time docs <br>
got hard to consume, I already knew the ropes. I don't know how hard it <br>
has been for newer contributors to join since then and how much of the <br>
difficulty is related to docs.<br>
<br>
I'm not sure I've said anything useful, so apologies for derailing the <br>
discussion if I've done that.<br>
<br>
-melanie<br>
<br>
<br>
</blockquote></div><br clear="all"><div>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.</div><div>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</div><div>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. </div><div>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</div><div>a "we have the content and the wisdom, so let's build something that someone can put in prod and stand on it."</div><div><br></div><div>From my perspective this has literally been our barrier to adoption. <br></div>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div>~/DonnyD</div><div>C: 805 814 6800</div><div>"No mission too difficult. No sacrifice too great. Duty First"</div></div></div></div>