Open Stack

On September 13, 2017 at 11:47:16, Mike Perez (thingee at gmail.com) wrote:
> 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
>