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 <[email protected]
<mailto:[email protected]>> 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
<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 <[email protected] <mailto:[email protected]>>
*Reply-To: *"OpenStack Development Mailing List (not for usage
questions)" <[email protected]
<mailto:[email protected]>>
*Date: *Friday, June 23, 2017 at 9:17 PM
*To: *OpenStack Development Mailing List
<[email protected]
<mailto:[email protected]>>
*Cc: *Wes Wilson <[email protected] <mailto:[email protected]>>,
"[email protected] <mailto:[email protected]>"
<[email protected] <mailto:[email protected]>>,
"[email protected] <mailto:[email protected]>"
<[email protected] <mailto:[email protected]>>
*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/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
<http://docs.openstack.org/upstream-training/irc.html>____
[2] - http://docs.openstack.org/upstream-training/git.html
<http://docs.openstack.org/upstream-training/git.html>____
[3] - http://docs.openstack.org/upstream-training/accounts.html
<http://docs.openstack.org/upstream-training/accounts.html>____
[4] -
https://www.dropbox.com/s/o46xh1cp0sv0045/OpenStack%20contributor%20portal.pdf?dl=0
<https://www.dropbox.com/s/o46xh1cp0sv0045/OpenStack%20contributor%20portal.pdf?dl=0>____
__ __
—____
__ __
Mike Perez____
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe:
[email protected]?subject:unsubscribe
<http://[email protected]?subject:unsubscribe>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
