Re: [openstack-dev] Contributor Portal PTG Recap

[Petr Kovar]

Hi all,

Just a quick update on how the contributor portal project will be
organized.

We created a new subteam under the Documentation Project.
This subteam (specialty team), led by Mike, will maintain the
portal repo openstack/contributor-guide.

Patches addressing this have been merged:

https://review.openstack.org/#/q/Ib8062210854e1979aa1f56bd7c0f5af8e578decc

Thanks,
pk


On Fri, 22 Sep 2017 11:13:46 -0700
Mike Perez  wrote:

> # Contributor Portal Next Steps
> 
> ## Landing Page Mock ups
> * Current mock up:
> https://drive.google.com/file/d/0BxMh9oiou2xMLVRvRWRFVklHa2c/view
> * Limited click through mock up:
> https://invis.io/CSDEZTBDJ#/252645774_Landing
> 
> ## Todo
> - [ ] thingee: A proposal for the *second level* of what the landing page
> shows.
> - [ ] thingee: Follow up with the Wes and Jimmy at the OpenStack Foundation
> for design assistance.
> 
> ## Communication To The Community
> * [Initial
> email](http://lists.openstack.org/pipermail/openstack-dev/2017-June/118877.html)
> * [Initial full
> thread](http://lists.openstack.org/pipermail/openstack-dev/2017-June/thread.html#118877)
> 
> ## Highlights from PTG session
> [OpenStack Etherpad](https://etherpad.openstack.org/p/contributor-portal)
> 
> ### TLDR (big changes from discussion)
> * Instead of all team on-boarding documentation living in a central
> repository, it will still remain with the individual teams to maintain in
> their own repository. General documentation (e.g. git, creating accounts,
> gerrit setup, etc) will still live in this central repo. If you choose to
> contribute by code for example and you pick a project, it will take you
> through our general documentation, then the project’s specific documentation.
> * This could lead to inconsistencies in documentation design? Confusion
> for the reader being sent to different pages?
> 
> ### General
> * We can’t go based off services. Not everything people are contributing
> to is a service, so they won't have anything corresponding in the
> [service type authority
> repo](http://git.openstack.org/cgit/openstack/service-types-authority/tree/service-types.yaml).
> There might be a field in projects.yaml that can help with this.
> * Remind Thierry on the service type authority repo for
> grouping/mapping project.
> * Videos were considered, but they’re hard to keep up-to-date.
> Previous Documentation PTL Alexandra Settle expressed that even
> screenshots can get out of date real fast. 
> * Generate some kind of crash-course / cheatsheet content for people
> who are used to GitHub but not familiar with Gerrit. Aspiers
> volunteered for this and made this first pass [ethercalc
> sheet](https://ethercalc.openstack.org/github-gerrit).
> * Translation team needs to be included
> * Provide documentation with how to edit the landing page, since the
> source is being hosted on github (there are transition discussions in
> place with the infra team and Jimmy)
> * Help projects with creating their own contributor guides if they
> need to. Think of something like Cookie cutter for setting up the
> scaffolding for a new OpenStack project, but getting projects
> contributor guides going.
> 
> ### Upstream Institute
> Attendees of the session we’re more in favor of projects keeping
> their specific documentation owned in their repositories. As learned
> from the centralize documentation problem
> [1](http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html)
> [2](https://doughellmann.com/blog/2017/08/24/stop-working-so-hard-scaling-open-source-community-practices/)
> [3](https://governance.openstack.org/tc/reference/top-5-help-wanted.html#documentation-owners),
> this is a good move. Upstream institute would then use whatever
> general documentation is provided. If people get past that, we could
> even suggest on-boarding to one of the [top 5 most wanted
> help](https://governance.openstack.org/tc/reference/top-5-help-wanted.html)!
> 
> ### User Committee
> Lauren Sell worked with Melvin and others from the user committee to get their
> requirements and perspective on the project. Here's an ether pad:
> https://etherpad.openstack.org/p/contributor-portal-user-section
> 
> ### Mock Up Feedback
> * Having the service types is great, but on the next level it would
> be good to express the code name with a description of what the
> project does.
> * Combine in events OpenStack day, meetups, forum, ptg, etc.
> (emphasize on in person thing)
> 
> ### Bikeshed
> * A word that combines code and documentation ("team(s)" was already
> rejected)
> 
> -- 
> 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-dev] Contributor Portal PTG Recap

[Mike Perez]

# Contributor Portal Next Steps

## Landing Page Mock ups
* Current mock up:
https://drive.google.com/file/d/0BxMh9oiou2xMLVRvRWRFVklHa2c/view
* Limited click through mock up:
https://invis.io/CSDEZTBDJ#/252645774_Landing

## Todo
- [ ] thingee: A proposal for the *second level* of what the landing page
shows.
- [ ] thingee: Follow up with the Wes and Jimmy at the OpenStack Foundation
for design assistance.

## Communication To The Community
* [Initial
email](http://lists.openstack.org/pipermail/openstack-dev/2017-June/118877.html)
* [Initial full
thread](http://lists.openstack.org/pipermail/openstack-dev/2017-June/thread.html#118877)

## Highlights from PTG session
[OpenStack Etherpad](https://etherpad.openstack.org/p/contributor-portal)

### TLDR (big changes from discussion)
* Instead of all team on-boarding documentation living in a central
repository, it will still remain with the individual teams to maintain in
their own repository. General documentation (e.g. git, creating accounts,
gerrit setup, etc) will still live in this central repo. If you choose to
contribute by code for example and you pick a project, it will take you
through our general documentation, then the project’s specific documentation.
* This could lead to inconsistencies in documentation design? Confusion
for the reader being sent to different pages?

### General
* We can’t go based off services. Not everything people are contributing
to is a service, so they won't have anything corresponding in the
[service type authority
repo](http://git.openstack.org/cgit/openstack/service-types-authority/tree/service-types.yaml).
There might be a field in projects.yaml that can help with this.
* Remind Thierry on the service type authority repo for
grouping/mapping project.
* Videos were considered, but they’re hard to keep up-to-date.
Previous Documentation PTL Alexandra Settle expressed that even
screenshots can get out of date real fast. 
* Generate some kind of crash-course / cheatsheet content for people
who are used to GitHub but not familiar with Gerrit. Aspiers
volunteered for this and made this first pass [ethercalc
sheet](https://ethercalc.openstack.org/github-gerrit).
* Translation team needs to be included
* Provide documentation with how to edit the landing page, since the
source is being hosted on github (there are transition discussions in
place with the infra team and Jimmy)
* Help projects with creating their own contributor guides if they
need to. Think of something like Cookie cutter for setting up the
scaffolding for a new OpenStack project, but getting projects
contributor guides going.

### Upstream Institute
Attendees of the session we’re more in favor of projects keeping
their specific documentation owned in their repositories. As learned
from the centralize documentation problem
[1](http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html)
[2](https://doughellmann.com/blog/2017/08/24/stop-working-so-hard-scaling-open-source-community-practices/)
[3](https://governance.openstack.org/tc/reference/top-5-help-wanted.html#documentation-owners),
this is a good move. Upstream institute would then use whatever
general documentation is provided. If people get past that, we could
even suggest on-boarding to one of the [top 5 most wanted
help](https://governance.openstack.org/tc/reference/top-5-help-wanted.html)!

### User Committee
Lauren Sell worked with Melvin and others from the user committee to get their
requirements and perspective on the project. Here's an ether pad:
https://etherpad.openstack.org/p/contributor-portal-user-section

### Mock Up Feedback
* Having the service types is great, but on the next level it would
be good to express the code name with a description of what the
project does.
* Combine in events OpenStack day, meetups, forum, ptg, etc.
(emphasize on in person thing)

### Bikeshed
* A word that combines code and documentation ("team(s)" was already
rejected)

-- 
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