Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

We now have an ether pad

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

—
Mike Perez

On September 13, 2017 at 11:47:16, Mike Perez (thin...@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 (thin...@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
>

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

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 (thin...@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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

+ OpenStack dev list

On June 29, 2017 at 13:01:09, Amy Marrich (a...@demarco.com) wrote:
> First off it looks really sleek and I love the look! A few thoughts though
> and I do realize it's just a mock up:
>
> 1) We have Sponsor just to pick one but don't have Operators/Administrators
> and their feedback is a major contribution so please don't leave them out.

Ah yes, I should’ve mentioned earlier that this is totally a POC.
There are lots missing, don’t worry! :)

> 2) I would list the contributor types in alphabetical order that way no
> group feels slighted, you can't help it if Use Cases are last it's just
> that they start with a U vs Code which is a C.

Sure!

> 3) What if you would like to contribute in multiple ways?

You would come back to the main contributor portal and click on a
different contribution. How about at the end of each lesson it gives
them the option to go back to main contributor portal to pick another
way to contribute?

>
> Resources are definitely still underdevelopment there but are they meant to
> be broad applicable to all resources with more specialized one's visible
> when you click on how you'd like to contribute?

That’s a good question. I think it should probably on top contain the
more general stuff, then in alphabetical order we can list resources
for all contribution types? It can be like the “I want to contribute
to OpenStack by…” top piece, but instead lists resource links to pick
through based on your contribution type(s). Maybe we keep them as
separate pages as originally given in the mock up so it’s not overly
crowded?

Thanks for the help Amy!

—
Mike Perez

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

+ OpenStack dev list

Hello all,

Wes has just took my ugly mock up of the contributor portal idea and
came up with this [1].

Here’s what he said:

"The idea is to help get potential contributors to the right place,
using the outline Mike put together. Rather than sending people to a
different page for each contribution type, users would be able to see
what options are available all on this page. We’d send them to any
necessary page(s) once they’ve gone through this quasi-wizard. Is this
along the lines of what you were thinking? page 2 shows the view once
you’ve clicked “Code” on page 1 (just in case that wasn’t super
obvious) Thanks!”

What do you all think? This does change things a bit of instead of the
landing page being more obvious of a resource of links, it’s both for
new and current contributors. Current contributors would hopefully be
able to see the resource links below.

Keep in mind that we will be working in the “Top 5 requested help” and
as suggested by Clark, an option of “I don’t know where I want to
start, but I want to help” kind of option. This would direct people to
resources such as Upstream University, mentor program, low hanging
fruit, that release priority idea I talked about earlier, etc.

Personally I like it!


[1] - https://www.dropbox.com/s/3q172qwfkik1ysd/contributor-portal.pdf?dl=0

—
Mike Perez

> On June 27, 2017 at 13:48:36, Mike Perez (thin...@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
> > * 

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

On 22:18 Jun 27, Jeremy Stanley wrote:
> On 2017-06-27 14:34:46 -0700 (-0700), Mike Perez wrote:
> [...]
> > ## PTG
> > 
> > New contributors should be participating in the sessions for a
> > project and get to know who are the people leading those efforts.
> > People leading efforts want help. Whether it be documentation for
> > the thing, implementation, testing, etc. Working with the people
> > involved is a good way to get to know that feature or change. The
> > people leading the effort are now invested in YOU succeeding
> > because if you don't succeed, they don't either. Once you succeed
> > in the feature or change with someone, you have recognition in
> > people knowing you are responsible for it in some way. This is an
> > awesome feeling and will lead you to either improving it more or
> > going onto other things. While you're only understanding of a
> > project is that thing, you may get curious and move onto other
> > parts of the code. This leads to someone in the future leading
> > efforts for new contributors!
> [...]
> 
> If you mean "junior" contributors who have maybe gotten a small
> change merged or fixed a minor bug (but have at least figured out
> what team they probably want to spend a lot of their time helping
> on) then I agree. To me "new" contributors are the ones who still
> need the basics of how to submit a patch, where to find bug reports,
> or whatever and those are being catered to at the Forum (via
> OpenStack 101, Upstream Institute, project onboarding), not the PTG.

Yes I'm talking about both junior and new contributors in the way you're
defining them. If they're new, they can still participate in discussions and
meet the people leading an effort. Processes with launchpad/gerrit etc is all
just tools that can be learned later. Learning these processes should just be
followed up later with the looking at the new contributor portal with the
project they selected to work with and follow instructions and ask for help on
their IRC channel when needed.  

-- 
Mike Perez


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

On 00:07 Jun 28, Ildiko Vancsa wrote:


 
> > On 2017. Jun 27., at 23:34, Mike Perez  wrote:
> > 
> > On 13:52 Jun 23, Michał Jastrzębski wrote:
> >> Great idea!
> >> 
> >> I would also throw another issue new people often have (I had it too).
> >> Namely what to contribute. Lot's of people wants to do something but
> >> not quite know where to start.
> >> So few ideas for start:
> >> * List of triaged bugs
> >> * List of work items of large blueprits
> > 
> > IMO the triaged bugs/low hanging fruit thing seems to be still daunting for 
> > new
> > contributors. There's also not really much gratification or recognition for
> > what you did by the wider community sometimes. This is something I feel that
> > helps in having people come back to contribute.
> 
> From maintenance perspective I would ensure new comers are aware how to find
> those, but don’t give an exact list.
> 
> By having the Project On-boarding sessions, etc. and a bit more focus on
> coaching and mentoring we might be able to get some attention from projects
> regarding maintaining the list of low hanging fruit bugs. Sometimes that tag
> is not really verified and there are also cases when it does not get marked
> as fixed or obsolete. From earlier experience they are not always
> encouraging...
> 
> > This is going on a tangent of something else I have coming in the future but
> > I think there are a few ways a new contributor would come in:
> > 
> > ## PTG
> > 
> > New contributors should be participating in the sessions for a project and
> > get to know who are the people leading those efforts. People leading efforts
> > want help. Whether it be documentation for the thing, implementation, 
> > testing,
> > etc. Working with the people involved is a good way to get to know that 
> > feature
> > or change. The people leading the effort are now invested in YOU succeeding
> > because if you don't succeed, they don't either. Once you succeed in the
> > feature or change with someone, you have recognition in people knowing you 
> > are
> > responsible for it in some way. This is an awesome feeling and will lead 
> > you to
> > either improving it more or going onto other things. While you're only
> > understanding of a project is that thing, you may get curious and move onto
> > other parts of the code. This leads to someone in the future leading efforts
> > for new contributors!
> 
> I think for this we need to encourage people to attend the Summit first and
> come to an On-boarding session if their target project has one. From my
> experience when I attended my first Design Summit I had no clue what’s going
> on and that can be very discouraging and I saw people for whom it was. And in
> my opinion we also cannot expect the project teams to baby sit new people on
> the PTG.
> 
> With that said, I agree we should have new people on this event, but I think
> we need to be more careful with describing and clarifying prerequisites and
> expectations, like basic knowledge of the area and experience or just to do
> their research before they come and they should know this event is not
> focusing on them.
> 
> The portal should be a great place to describe all this and give a list of
> best practices!

I agree. I just know people are going to come regardless of no matter how many
warning signs you throw in front of them. A quick intro into each session that
this going to move fast/has been discussed and not exactly new contributor
friendly but if you are interested in the effort being discussed find . This is just an answer for those people that
miss all those warnings.

> > ## Forum
> > 
> > I would like to see our on-boarding rooms having time to introduce
> > current/future efforts happening in the project. Introduce the people behind
> > those efforts. Give a little time to break out into meet and greet to 
> > remember
> > friendly faces and do as mentioned above.
> 
> +1
> 
> > 
> > ## Internet
> > 
> > People may not be able to attend our events, but want to participate. Using
> > your idea of listing work items of large blueprints is an excellent! It 
> > would
> > be good if we could list those cleanly and who is leading it. Maybe 
> > Storyboard
> > will be able to help with this in the future Kendall?
> 
> Do we/can we have a tag for large blueprints? So we could teach people how to
> find this and give them a search link, etc.?

Either storyboard allows us to filter on the stuff the project teams have set
for a release, or we just use its API and build our own clean listing.


-- 
Mike Perez


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Jeremy Stanley]

On 2017-06-27 14:34:46 -0700 (-0700), Mike Perez wrote:
[...]
> ## PTG
> 
> New contributors should be participating in the sessions for a
> project and get to know who are the people leading those efforts.
> People leading efforts want help. Whether it be documentation for
> the thing, implementation, testing, etc. Working with the people
> involved is a good way to get to know that feature or change. The
> people leading the effort are now invested in YOU succeeding
> because if you don't succeed, they don't either. Once you succeed
> in the feature or change with someone, you have recognition in
> people knowing you are responsible for it in some way. This is an
> awesome feeling and will lead you to either improving it more or
> going onto other things. While you're only understanding of a
> project is that thing, you may get curious and move onto other
> parts of the code. This leads to someone in the future leading
> efforts for new contributors!
[...]

If you mean "junior" contributors who have maybe gotten a small
change merged or fixed a minor bug (but have at least figured out
what team they probably want to spend a lot of their time helping
on) then I agree. To me "new" contributors are the ones who still
need the basics of how to submit a patch, where to find bug reports,
or whatever and those are being catered to at the Forum (via
OpenStack 101, Upstream Institute, project onboarding), not the PTG.
-- 
Jeremy Stanley


signature.asc
Description: Digital signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Kendall Nelson]

Storyboard can definitely help with this! Each task in a story has an owner
and a project while the larger story's description could list who is in
charge of the larger implementation overall.

On Tue, Jun 27, 2017 at 4:34 PM Mike Perez  wrote:

> On 13:52 Jun 23, Michał Jastrzębski wrote:
> > Great idea!
> >
> > I would also throw another issue new people often have (I had it too).
> > Namely what to contribute. Lot's of people wants to do something but
> > not quite know where to start.
> > So few ideas for start:
> > * List of triaged bugs
> > * List of work items of large blueprits
>
> IMO the triaged bugs/low hanging fruit thing seems to be still daunting
> for new
> contributors. There's also not really much gratification or recognition for
> what you did by the wider community sometimes. This is something I feel
> that
> helps in having people come back to contribute.
>
> This is going on a tangent of something else I have coming in the future
> but
> I think there are a few ways a new contributor would come in:
>
> ## PTG
>
> New contributors should be participating in the sessions for a project and
> get to know who are the people leading those efforts. People leading
> efforts
> want help. Whether it be documentation for the thing, implementation,
> testing,
> etc. Working with the people involved is a good way to get to know that
> feature
> or change. The people leading the effort are now invested in YOU succeeding
> because if you don't succeed, they don't either. Once you succeed in the
> feature or change with someone, you have recognition in people knowing you
> are
> responsible for it in some way. This is an awesome feeling and will lead
> you to
> either improving it more or going onto other things. While you're only
> understanding of a project is that thing, you may get curious and move onto
> other parts of the code. This leads to someone in the future leading
> efforts
> for new contributors!
>
> ## Forum
>
> I would like to see our on-boarding rooms having time to introduce
> current/future efforts happening in the project. Introduce the people
> behind
> those efforts. Give a little time to break out into meet and greet to
> remember
> friendly faces and do as mentioned above.
>
> ## Internet
>
> People may not be able to attend our events, but want to participate. Using
> your idea of listing work items of large blueprints is an excellent! It
> would
> be good if we could list those cleanly and who is leading it. Maybe
> Storyboard
> will be able to help with this in the future Kendall?
>
> --
> Mike Perez
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

On 13:52 Jun 23, Michał Jastrzębski wrote:
> Great idea!
> 
> I would also throw another issue new people often have (I had it too).
> Namely what to contribute. Lot's of people wants to do something but
> not quite know where to start.
> So few ideas for start:
> * List of triaged bugs
> * List of work items of large blueprits

IMO the triaged bugs/low hanging fruit thing seems to be still daunting for new
contributors. There's also not really much gratification or recognition for
what you did by the wider community sometimes. This is something I feel that
helps in having people come back to contribute.

This is going on a tangent of something else I have coming in the future but
I think there are a few ways a new contributor would come in:

## PTG

New contributors should be participating in the sessions for a project and
get to know who are the people leading those efforts. People leading efforts
want help. Whether it be documentation for the thing, implementation, testing,
etc. Working with the people involved is a good way to get to know that feature
or change. The people leading the effort are now invested in YOU succeeding
because if you don't succeed, they don't either. Once you succeed in the
feature or change with someone, you have recognition in people knowing you are
responsible for it in some way. This is an awesome feeling and will lead you to
either improving it more or going onto other things. While you're only
understanding of a project is that thing, you may get curious and move onto
other parts of the code. This leads to someone in the future leading efforts
for new contributors!

## Forum

I would like to see our on-boarding rooms having time to introduce
current/future efforts happening in the project. Introduce the people behind
those efforts. Give a little time to break out into meet and greet to remember
friendly faces and do as mentioned above.

## Internet

People may not be able to attend our events, but want to participate. Using
your idea of listing work items of large blueprints is an excellent! It would
be good if we could list those cleanly and who is leading it. Maybe Storyboard
will be able to help with this in the future Kendall?

-- 
Mike Perez


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

On 09:45 Jun 26, Alexandra Settle wrote:
> I think this is a good idea :) thanks Mike. We get a lot of people coming to
> the docs chan or ML asking for help/where to start and sometimes it’s
> difficult to point them in the right direction.
> 
> Just from experience working with contributor documentation, I’d avoid all
> screen shots if you can – updating them whenever the process changes
> (surprisingly often) is a lot of unnecessary technical debt.

I understand and agree. This was a big selling point to contributors I've spoke
to about this though in avoid walls of text so it's actually something seeming
doable. Perhaps having a small number of steps to a page can still give the
reader a feeling they can finish it in five minutes or less?

> The docs team put a significant amount of effort in a few releases back
> writing a pretty comprehensive Contributor Guide. For the purposes you
> describe below, I imagine a lot of the content here could be adapted. The
> process of setting up for code and docs is exactly the same:
> http://docs.openstack.org/contributor-guide/index.html

Yes I've seen this content and do plan to adapt stuff over!

> 
> I also wonder if we could include a ‘what is openstack’ 101 for new
> contributors. I find that there is a *lot* of material out there, but it is
> often very hard to explain to people what each project does, how they all
> interact, why we install from different sources, why do we have official and
> unofficial projects etc. It doesn’t have to be seriously in-depth, but an
> overview that points people who are interested in the right directions. Often
> this will help people decide on what project they’d like to undertake.

Wonderful idea. I cc'd Anne from the Openstack Foundation who is helping with
this effort. We will be discussing soon on incorporating 101 content over.

-- 
Mike Perez


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Joshua Harlow]

Boris Pavlovic wrote:


Overall it would take 1-2 days for people not familiar with OpenStack.

What about if one make "Sing-Up" page:

1) Few steps: provide Username, Contact info, Agreement, SSH key (and it
will do all work for you set Gerrit, OpenStack,...)
2) After one finished form it gets instruction for his OS how to setup
and run properly git review
3) Maybe few tutorials (how to find some bug, how to test it and where
are the docs, devstack, ...)


Sounds nice.

I wouldn't mind this as I also saw how painful it was (with the same 
intern).




That would simplify onboarding process...

Best regards,
Boris Pavlovic

On Mon, Jun 26, 2017 at 2:45 AM, Alexandra Settle > wrote:

I think this is a good idea :) thanks Mike. We get a lot of people
coming to the docs chan or ML asking for help/where to start and
sometimes it’s difficult to point them in the right direction.

__ __

Just from experience working with contributor documentation, I’d
avoid all screen shots if you can – updating them whenever the
process changes (surprisingly often) is a lot of unnecessary
technical debt.

__ __

The docs team put a significant amount of effort in a few releases
back writing a pretty comprehensive Contributor Guide. For the
purposes you describe below, I imagine a lot of the content here
could be adapted. The process of setting up for code and docs is
exactly the same:
http://docs.openstack.org/contributor-guide/index.html
 

__ __

I also wonder if we could include a ‘what is openstack’ 101 for new
contributors. I find that there is a **lot** of material out there,
but it is often very hard to explain to people what each project
does, how they all interact, why we install from different sources,
why do we have official and unofficial projects etc. It doesn’t have
to be seriously in-depth, but an overview that points people who are
interested in the right directions. Often this will help people
decide on what project they’d like to undertake.

__ __

Cheers,

__ __

Alex

__ __

*From: *Mike Perez >
*Reply-To: *"OpenStack Development Mailing List (not for usage
questions)" >
*Date: *Friday, June 23, 2017 at 9:17 PM
*To: *OpenStack Development Mailing List
>
*Cc: *Wes Wilson >,
"ild...@openstack.org "
>,
"knel...@openstack.org "
>
*Subject: *[openstack-dev] [docs][all][ptl] Contributor Portal and
Better New Contributor On-boarding

__ __

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:

  

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Jeremy Stanley]

On 2017-06-26 10:51:08 -0700 (-0700), Clark Boylan wrote:
> On Mon, Jun 26, 2017, at 10:31 AM, Boris Pavlovic wrote:
[...]
> > - When you try to contribute your first commit (if you already
> > created it, you won't be able unit you do git commit --ament, so
> > git review will add change-id)
> 
> Git review should automatically do this last step for you if a change id
> is missing.

Except if you're trying to push multiple commits you made before
installing the hook (then you need to go back and --amend them one
by one so Gerrit will accept them). Note this may be similarly
confusing when we eventually switch from the ICLA to the DCO, where
Gerrit will start rejecting your commits if you weren't already in
the habit of putting signed-off-by footers in all your commit
messages. Actually more confusing because we can't reasonably
automate that step away for anyone (since it loses its legal intent
if we did).

[...]
> I think that Jeremy (fungi) has work in progress to tie electoral rolls
> to foundation membership via an external lookup api that was recently
> added to the foundation membership site. This means that we shouldn't
> need to check that gerrit account info matches foundation account info
> at CLA signing tiem anymore (at least this is my understanding, Jeremy
> can correct me if I am wrong).
> 
> If this is the case it should make account setup much much simpler. You
> just add an ssh key and sign the cla without worrying about account
> details lining up.

Yes, but it _is_ going to significantly increase the risk of
contributors not qualifying to vote in technical elections or
receive event registration discounts if they choose (intentionally
or accidently) to not join the foundation or list different E-mail
addresses there vs. in Gerrit. We ought to preserve some means of
making sure they're still aware during onboarding that they might
want to take those extra steps.
-- 
Jeremy Stanley


signature.asc
Description: Digital signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Clark Boylan]

On Mon, Jun 26, 2017, at 10:31 AM, Boris Pavlovic wrote:
> Mike,
> 
> I was recently helping one Intern to join OpenStack community and make
> some
> contribution.
> 
> And I found that current workflow is extremely complex and I think not
> all
> people that want to contribute can pass it..
> 
> Current workflow is:
> - Go to Gerrit sign in
> - Find how to contirubte to Gerrit (fail with this because no ssh key)
> - Find in Gerrit where to upload ssh (because no agreement)
> - Find in Gerrit where to accept License agreement  (fail because your
> agreement is invalid and contact info should be provided in Gerrit)
> - Server can't accept contact infomration (is what you see in gerrit)
> - Go to OpenStack.org sign in (to fix the problem with Gerrit)
> - Update contact information
> - When you try to contribute your first commit (if you already created
> it,
> you won't be able unit you do git commit --ament, so git review will add
> change-id)

Git review should automatically do this last step for you if a change id
is missing.

> 
> Overall it would take 1-2 days for people not familiar with OpenStack.
> 
> 
> What about if one make  "Sing-Up" page:
> 
> 1) Few steps: provide Username, Contact info, Agreement, SSH key (and it
> will do all work for you set Gerrit, OpenStack,...)
> 2) After one finished form it gets instruction for his OS how to setup
> and
> run properly git review
> 3) Maybe few tutorials (how to find some bug, how to test it and where
> are
> the docs, devstack, ...)
> 
> That would simplify onboarding process...

I think that Jeremy (fungi) has work in progress to tie electoral rolls
to foundation membership via an external lookup api that was recently
added to the foundation membership site. This means that we shouldn't
need to check that gerrit account info matches foundation account info
at CLA signing tiem anymore (at least this is my understanding, Jeremy
can correct me if I am wrong).

If this is the case it should make account setup much much simpler. You
just add an ssh key and sign the cla without worrying about account
details lining up.

Clark

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Amy Marrich]

Mike,

We've gone through some of this with the Git and Gerrit Lunch and Learns
and the Upstream Institute, but those are both live teaching type
situations. I'd be more then happy to help incorporate some of the stuff we
already have into an on-line effort for those who can't attend in person so
that we can help get them the same experience if not close to it.

Amy (aka spotz)

On Fri, Jun 23, 2017 at 3:17 PM, Mike Perez  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
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
__
OpenStack 

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Boris Pavlovic]

Mike,

I was recently helping one Intern to join OpenStack community and make some
contribution.

And I found that current workflow is extremely complex and I think not all
people that want to contribute can pass it..

Current workflow is:
- Go to Gerrit sign in
- Find how to contirubte to Gerrit (fail with this because no ssh key)
- Find in Gerrit where to upload ssh (because no agreement)
- Find in Gerrit where to accept License agreement  (fail because your
agreement is invalid and contact info should be provided in Gerrit)
- Server can't accept contact infomration (is what you see in gerrit)
- Go to OpenStack.org sign in (to fix the problem with Gerrit)
- Update contact information
- When you try to contribute your first commit (if you already created it,
you won't be able unit you do git commit --ament, so git review will add
change-id)

Overall it would take 1-2 days for people not familiar with OpenStack.


What about if one make  "Sing-Up" page:

1) Few steps: provide Username, Contact info, Agreement, SSH key (and it
will do all work for you set Gerrit, OpenStack,...)
2) After one finished form it gets instruction for his OS how to setup and
run properly git review
3) Maybe few tutorials (how to find some bug, how to test it and where are
the docs, devstack, ...)

That would simplify onboarding process...

Best regards,
Boris Pavlovic

On Mon, Jun 26, 2017 at 2:45 AM, Alexandra Settle <a.set...@outlook.com>
wrote:

> I think this is a good idea :) thanks Mike. We get a lot of people coming
> to the docs chan or ML asking for help/where to start and sometimes it’s
> difficult to point them in the right direction.
>
>
>
> Just from experience working with contributor documentation, I’d avoid all
> screen shots if you can – updating them whenever the process changes
> (surprisingly often) is a lot of unnecessary technical debt.
>
>
>
> The docs team put a significant amount of effort in a few releases back
> writing a pretty comprehensive Contributor Guide. For the purposes you
> describe below, I imagine a lot of the content here could be adapted. The
> process of setting up for code and docs is exactly the same:
> http://docs.openstack.org/contributor-guide/index.html
>
>
>
> I also wonder if we could include a ‘what is openstack’ 101 for new
> contributors. I find that there is a **lot** of material out there, but
> it is often very hard to explain to people what each project does, how they
> all interact, why we install from different sources, why do we have
> official and unofficial projects etc. It doesn’t have to be seriously
> in-depth, but an overview that points people who are interested in the
> right directions. Often this will help people decide on what project they’d
> like to undertake.
>
>
>
> Cheers,
>
>
>
> Alex
>
>
>
> *From: *Mike Perez <thin...@gmail.com>
> *Reply-To: *"OpenStack Development Mailing List (not for usage
> questions)" <openstack-dev@lists.openstack.org>
> *Date: *Friday, June 23, 2017 at 9:17 PM
> *To: *OpenStack Development Mailing List <openstack-dev@lists.
> openstack.org>
> *Cc: *Wes Wilson <w...@openstack.org>, "ild...@openstack.org" <
> ild...@openstack.org>, "knel...@openstack.org" <knel...@openstack.org>
> *Subject: *[openstack-dev] [docs][all][ptl] Contributor Portal and Better
> New Contributor On-boarding
>
>
>
> 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:
>
>  

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Alexandra Settle]

I think this is a good idea :) thanks Mike. We get a lot of people coming to 
the docs chan or ML asking for help/where to start and sometimes it’s difficult 
to point them in the right direction.

Just from experience working with contributor documentation, I’d avoid all 
screen shots if you can – updating them whenever the process changes 
(surprisingly often) is a lot of unnecessary technical debt.

The docs team put a significant amount of effort in a few releases back writing 
a pretty comprehensive Contributor Guide. For the purposes you describe below, 
I imagine a lot of the content here could be adapted. The process of setting up 
for code and docs is exactly the same: 
http://docs.openstack.org/contributor-guide/index.html

I also wonder if we could include a ‘what is openstack’ 101 for new 
contributors. I find that there is a *lot* of material out there, but it is 
often very hard to explain to people what each project does, how they all 
interact, why we install from different sources, why do we have official and 
unofficial projects etc. It doesn’t have to be seriously in-depth, but an 
overview that points people who are interested in the right directions. Often 
this will help people decide on what project they’d like to undertake.

Cheers,

Alex

From: Mike Perez <thin...@gmail.com>
Reply-To: "OpenStack Development Mailing List (not for usage questions)" 
<openstack-dev@lists.openstack.org>
Date: Friday, June 23, 2017 at 9:17 PM
To: OpenStack Development Mailing List <openstack-dev@lists.openstack.org>
Cc: Wes Wilson <w...@openstack.org>, "ild...@openstack.org" 
<ild...@openstack.org>, "knel...@openstack.org" <knel...@openstack.org>
Subject: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New 
Contributor On-boarding

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<http://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/chapter

Re: [openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Michał Jastrzębski]

Great idea!

I would also throw another issue new people often have (I had it too).
Namely what to contribute. Lot's of people wants to do something but
not quite know where to start.
So few ideas for start:
* List of triaged bugs
* List of work items of large blueprits

Thoughts,
Michal

On 23 June 2017 at 13:17, Mike Perez  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
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 

[openstack-dev] [docs][all][ptl] Contributor Portal and Better New Contributor On-boarding

[Mike Perez]

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
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev