Open Stack

Hey all,

We’ll be meeting with the Documentation team at the ptg in ballroom c
today at 14:30 local time to discuss progress. Join us and lets help
make our on-boarding experience better for new contributors!

—
Mike Perez

On June 23, 2017 at 14:17:07, Mike Perez (thingee at gmail.com) wrote:
>
>
> 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