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