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 ([email protected]) 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 ([email protected]) 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: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
