Open Stack

Hello all,

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.

Suggestion: lets work our efforts together to create some common
documentation so that all teams in OpenStack can benefit.

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!

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.

A team might use special tools to do their work. These can also be
integrated in this idea as well.

Once we have common documentation we can have something like:
    1. Choose your own adventure: I want to contribute by code
    2. What service type are you interested in? (Database, Block storage,
compute)
    3. Here’s step-by-step common documentation to setting up Git, IRC,
Mailing Lists, Accounts, etc.
    4. A service type project might choose to also include additional
documentation in that flow for special tools, etc.

Important things to note in this flow:
    * How do you want to contribute?
    * Here are **clear** names that identify the team. Not code names like
Cloud Kitty, Cinder, etc.
    * The documentation should really aim to not be daunting:
    * 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
    * No wall of text!
    * Use screen shots
    * Avoid covering every issue you could hit along the way.

## Examples of More Simple Documentation
I worked on some documentation for the Upstream University preparation that
has received excellent feedback meet close to these suggestions:
    * IRC [1]
    * Git [2]
    * Account Setup [3]

## 500 Feet Birds Eye view
There will be a Contributor landing page on the openstack.org 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.

Here's an example of what the sections/chapters could look like:

- Code
        * Volumes (Cinder)
             * IRC
             * Git
             * Account Setup
             * Generating Configs
        * Compute (Nova)
             * IRC
             * Git
             * Account Setup
        * Something about hypervisors (matrix?)
-  Use Cases
* Products (Product working group)
* IRC
    * Git
* Use Case format

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?

[1] - http://docs.openstack.org/upstream-training/irc.html
[2] - http://docs.openstack.org/upstream-training/git.html
[3] - http://docs.openstack.org/upstream-training/accounts.html
[4] -
https://www.dropbox.com/s/o46xh1cp0sv0045/OpenStack%20contributor%20portal.pdf?dl=0

—

Mike Perez
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170623/4d060620/attachment.html>