<html><head></head><body><div></div><div>
<title></title>
<div></div>
<div>Hello all,</div><div><br></div><div>Every month we have people asking on IRC or the dev mailing list having interest in working on OpenStack, and sometimes they're given different answers from people, or worse, no answer at all.<div><br></div>
<div>
<div>Suggestion: lets work our efforts together to create some
common documentation so that all teams in OpenStack can
benefit.</div>
<div><br></div>
<div>First it’s important to note that we’re not just talking about
code projects here. OpenStack contributions come in many forms such
as running meet ups, identifying use cases (product working group),
documentation, testing, etc. We want to make sure those potential
contributors feel welcomed too!</div>
<div><br></div>
<div>What is common documentation? Things like setting up Git, the
many accounts you need to setup to contribute (gerrit, launchpad,
OpenStack foundation account). Not all teams will use some common
documentation, but the point is one or more projects will use
them. Having the common documentation worked on by various projects will better help prevent duplicated efforts, inconsistent documentation, and hopefully just more accurate information.</div>
<div><br></div>
<div>A team might use
special tools to do their work. These can also be integrated in
this idea as well.</div>
<div><br></div>
<div>Once we have common documentation we can have something
like:</div>
<div> 1. Choose your own adventure: I want to
contribute by code</div>
<div> 2. What service type are you interested in?
(Database, Block storage, compute)</div>
<div> 3. Here’s step-by-step common documentation to setting
up Git, IRC, Mailing Lists, Accounts, etc.</div>
<div> 4. A service type project might choose to also
include additional documentation in that flow for special tools,
etc.</div>
<div> </div>
<div>Important things to note in this flow:</div>
<div> * How do you want to contribute?</div>
<div> * Here are **clear** names that identify the
team. Not code names like Cloud Kitty, Cinder, etc.</div>
<div> * The documentation should really aim to not be
daunting:</div>
<div> * Someone should be able to glance at it and
feel like they can finish things in five minutes. Not be yet
another tab left in their browser that they’ll eventually forget
about</div>
<div> * No wall of text!</div>
<div> * Use screen shots</div>
<div> * Avoid covering every issue you could hit along
the way.</div>
<div><br></div>
<div>## Examples of More Simple Documentation</div>
<div>I worked on some documentation for the Upstream University
preparation that has received excellent feedback meet close to
these suggestions:</div>
<div> * IRC
[1]</div>
<div> * Git
[2]</div>
<div> * Account Setup
[3]</div>
<div><br></div>
<div>## 500 Feet Birds Eye view</div>
<div>There will be a Contributor landing page on the <a href="http://openstack.org">openstack.org</a> website. Existing contributors will find reference links to quickly jump to things. New
contributors will find a banner at the top of the page to direct them to the choose your own
adventure to contributing to OpenStack, with ordered documentation
flow that reuses existing documentation when necessary. Picture
also a progress bar somewhere to show how close you are to being
ready to contribute to whatever team. Of course there are a lot of
other fancy things we can come up with, but I think getting
something up as an initial pass would be better than what we have
today.</div>
<div><br></div>
<div>Here's an example of what the sections/chapters could look like:</div>
<div><br></div>
<div>- Code</div>
<div> * Volumes (Cinder)</div>
<div> * IRC</div>
<div> *
Git </div>
<div> * Account
Setup</div>
<div> * Generating
Configs</div>
<div> * Compute (Nova)</div>
<div> * IRC</div>
<div> * Git</div>
<div> * Account
Setup</div>
<div> * Something about hypervisors
(matrix?)</div>
<div>- Use Cases</div>
<div><span class="Apple-tab-span" style="white-space:pre"></span>*
Products (Product working group)</div>
<div><span class="Apple-tab-span" style="white-space:pre"></span>*
IRC</div>
<div> <span class="Apple-tab-span" style="white-space:pre"></span>* Git</div>
<div><span class="Apple-tab-span" style="white-space:pre"></span>*
Use Case format</div>
<div><br></div>
<div>There are some rough mock up ideas [4]. Probably Sphinx will be fine for this. Potentially we could use this content for conference lunch and learns, upstream university, and the on-boarding events at the Forum. What do you all think?</div>
<div><br></div><div>[1] - <span style="background-color:rgba(255,255,255,0)"><a href="http://docs.openstack.org/upstream-training/irc.html">http://docs.openstack.org/upstream-training/irc.html</a></span></div><div>[2] - <span style="background-color:rgba(255,255,255,0)"><a href="http://docs.openstack.org/upstream-training/git.html">http://docs.openstack.org/upstream-training/git.html</a></span></div><div>[3] - <span style="background-color:rgba(255,255,255,0)"><a href="http://docs.openstack.org/upstream-training/accounts.html">http://docs.openstack.org/upstream-training/accounts.html</a></span></div><div><span style="background-color:rgba(255,255,255,0)">[4] - </span><font color="#000000" style="background-color:rgba(255,255,255,0)"><a href="https://www.dropbox.com/s/o46xh1cp0sv0045/OpenStack%20contributor%20portal.pdf?dl=0" style="background-color:rgba(255,255,255,0)">https://www.dropbox.com/s/o46xh1cp0sv0045/OpenStack%20contributor%20portal.pdf?dl=0</a></font></div><br>
<div class="bloop_sign">
<div>—</div><div><br></div>
Mike Perez</div>
</div>
</div>
</div></body></html>