Open Stack

On Thu, Sep 14, 2017 at 05:08:41PM -0600, Adam Spiers wrote:
>One of the things discussed during this meeting was the idea of making
>it easier for some new developers to learn Gerrit based on their
>existing knowledge of GitHub.  I volunteered to assist with this and
>drafted this spreadsheet:
>
>  https://ethercalc.openstack.org/github-gerrit
>
>(Also linked from the etherpad.)
>
>The spreadsheet might be OK for more experienced git users, but for
>the less experienced we'll probably also need an accompanying document
>which spells things out in more detail.
>
>Feedback welcome.

Hi Adam,

thanks for creating this nice comparison! I think it's pretty complete.

As you write it's possibly too terse for beginners, but I suppose one has to start somewhere. :)

Thanks!

Nick

>Mike Perez <thingee at gmail.com> wrote:
>> 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
>> > >
>> >
>>
>> _______________________________________________
>> User-committee mailing list
>> User-committee at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/user-committee
>
>_______________________________________________
>User-committee mailing list
>User-committee at lists.openstack.org
>http://lists.openstack.org/cgi-bin/mailman/listinfo/user-committee