Open Stack

And now we have an ether pad

https://etherpad.openstack.org/p/contributor-portal

—
Mike Perez

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