Merge pull request #54 from paypal/contributing-revamp

README lists patterns MUCH better

Author: Nick Yeates

CONTRIBUTING.md

@@ -18,7 +18,7 @@ Select one of the following ways to contribute, to learn our workflow:
 
 # A. Writing a New Pattern
 
-The below steps can be used to create a new `donut`, `idea`, or complete pattern. The use-case here is that you have a relatively thought-out idea or problem in your head and can confidently fill out the barest of pattern fields (Solution doesn't need to be known). If you are unsure your idea is ready for this, [discuss it in an issue first](#discussing-early-ideas-in-issues).
+The below steps can be used to create a new `donut`, `idea`, or complete pattern. The use-case here is that you have a relatively thought-out idea or problem in your head and can confidently fill out the barest of pattern fields (Solution doesn't need to be known). If you are unsure your idea is ready for this, [discuss it in an issue first](#b-discussing-early-ideas-in-issues).
 
 The simplest way to create a pattern is with your browser:
 
@@ -27,7 +27,7 @@ The simplest way to create a pattern is with your browser:
 3. Name the file like this example: "project-management-time-pressures.md"
 4. Use the [pattern template](https://raw.githubusercontent.com/paypal/InnerSourcePatterns/master/meta/pattern-template.md) to create your new [markdown](/meta/markdown-info.md) file with the description of your _idea_, _donut_, or _pattern_
 5. Enter a commit message
-  * If you are asked to 'Commit directly' vs 'Create a new branch', see [branching details](#use-branches-when-creating-new-patterns).
+  * If you are asked to 'Commit directly' vs 'Create a new branch', see [branching details](#use-branches-when-creating-new-patterns) below.
 6. Propose this new file and then also create a Pull Request (PR)
 
 Your done! This creates a separate branch and creates a Pull Request (PR) all in one fell swoop! PR's are the mechanism we use for our multi-step Review process. See next steps in [Interacting with Pattern Reviews](#c-interacting-with-patterns-reviews).
@@ -43,7 +43,7 @@ If you are asked to 'Commit directly...' vs 'Create a new branch...'
 
 * Assure you select **'Create a new branch...'** and name the branch like this example: "pattern/project-management-time-pressures". 
 * This occurs when writing a new pattern via the web interface (section A above).
-* Only [Trusted Collaborators](/meta/trusted_collaborators.md) (TC's) are asked this; we are adding most contributors as TC's.
+* Only [Trusted Collaborators](/meta/trusted-collaborators.md) (TC's) are asked this; we are adding most contributors as TC's.
 
 
 
@@ -77,6 +77,6 @@ Below are the major steps in our Review process:
 2. Reviewers can now use the PR features to comment on the pattern.
 3. In case of required rework, the author should apply the labels `Ready for Additional Review` and/or `Revised` to indicate that a 2nd review is requested.
 4. After reviews are complete, the reviewers or author should remove the label `Ready for Review` and label the pattern `Accepted`.
-5. Once a pattern is `Accepted` by the reviewers, one of the [Trusted Collaborators](/meta/trusted_collaborators.md) (most authors are by this point) can  Merge the PR on Github. This places the .md file into the master branch / root directory.
+5. Once a pattern is `Accepted` by the reviewers, one of the [Trusted Collaborators](/meta/trusted-collaborators.md) (most authors are by this point) can  Merge the PR on Github. This places the .md file into the master branch / root directory.
 
-When completed patterns (reviewed and accepted) are ready to be published from this InnerSourcePatterns repo to the InnerSourcePatterns Gitbook, [see our separate PUBLISHING.md instructions](/meta/publishing.md).
+When completed patterns (reviewed and accepted) are ready to be published from this InnerSourcePatterns repo to a Gitbook (PDF), [see our separate Publishing instructions](/meta/publishing.md).

README.md

@@ -1,7 +1,7 @@
 This repository serves as the collection-point, ideation hub, and process behind the [InnerSource Commons'](http://innersourcecommons.com) set of proven and reviewed InnerSource approaches (patterns). These patterns illustrate beneficial activities and behaviors found in [organizations who apply InnerSource methodologies](http://paypal.github.io/InnerSourceCommons/getting-started/).
 
-What are Inner Source Patterns?
-===============================
+
+# What are Inner Source Patterns?
 
 Patterns are a way of describing a repeatable, proven solution to a problem with a context. They follow a simple form that helps people wanting to implement the solution to understand the constraints on the problem, the forces that must be balanced and the resulting context (the situation you are left with after the solution is applied). In inner sourcing, patterns can provide a way for the InnerSource Commons participants to concisely share information with each other, improving the practice of inner sourcing. Each of the patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections.
 
@@ -10,16 +10,14 @@ Patterns are a way of describing a repeatable, proven solution to a problem with
 * [View our InnerSource Patterns Template](meta/pattern-template.md)
 
 
-How can you use Inner Source Patterns?
-======================================
+# How can you use Inner Source Patterns?
 
 Patterns must be used in a thoughtful manner. They cannot be blindly applied. In most cases, you will need to adapt the given solution to your own situation; but the information given in the pattern, defining the context (immovable constraints) and forces (constraints that can be changed and balanced against each other), should help you do this.
 
 The pattern form is useful for describing proven patterns but it could also be used for *brainstorming solutions* where patterns are not yet established, since the form gives a structured way for thinking about a problem. You could also create a *donut pattern* (filling in the problem, context, forces and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try).
 
 
-How to Contribute?
-==================
+# How to Contribute?
 
 [See our CONTRIBUTING.md for details on getting involved](CONTRIBUTING.md)
 
@@ -28,14 +26,15 @@ We encourage beginners seeking answers to jump in by creating ''donuts'' (proble
 We work together via Github, Webex, Slack, etc. Do not hesitate to join the [#innersourcecommons](https://isc-inviter.herokuapp.com/) or #innersource-patterns slack channels and ask to be included in the [patterns meetings](/meta/meetings.md) (there is an email list).
 
 
-Reviewed Patterns (proven and reviewed)
-=======================================
+
+# List of Patterns
+
+#### Reviewed Patterns (proven and reviewed)
 
 * [Contracted Contributor](https://github.com/paypal/InnerSourcePatterns/blob/master/contracted-contributor.md)
 * [Dedicated Community Leader](https://github.com/paypal/InnerSourcePatterns/blob/master/dedicated-community-leader.md)
 
-Pattern Drafts (proven, not yet reviewed)
-=========================================
+#### Pattern Drafts (proven, not yet reviewed)
 
 * [Common Requirements](https://github.com/paypal/InnerSourcePatterns/pull/11)
 * [Reluctance to receive contributions](https://docs.google.com/document/d/13QDN-BpE_BixRFVGjao32n4Ctim0ROXAHbBWMBOijb4/edit)
@@ -47,8 +46,7 @@ Pattern Drafts (proven, not yet reviewed)
 * [Open Source trumps InnerSource](https://github.com/paypal/InnerSourceCommons/wiki/Open-Source-trumps-InnerSource)
 * [Overcoming Project Management Time Pressures](https://github.com/paypal/InnerSourceCommons/wiki/Draft-Pattern---Overcoming-Project-Management-Time-Pressures)
 
-Pattern Ideas (not yet proven; brainstormed)
-============================================
+#### Pattern Ideas (not yet proven; brainstormed)
 
 * [Badly named piles](https://github.com/paypal/InnerSourcePatterns/blob/master/badly-named-piles.md)
 * [Don't bother looking](https://github.com/paypal/InnerSourcePatterns/blob/master/dont-bother-looking.md)
@@ -58,8 +56,7 @@ Pattern Ideas (not yet proven; brainstormed)
 * [Change the developers mindset](https://github.com/paypal/InnerSourceCommons/wiki/Pattern:-change-the-developers-mindset)
 * [Share Your Code to Get More Done - Likely Contributors Variant](https://github.com/paypal/InnerSourceCommons/wiki/Pattern:-Share-Your-Code-to-Get-More-Done---Likely-Contributors-Variant)
 
-Pattern Donuts (needing a solution)
-===================================
+#### Pattern Donuts (needing a solution)
 
 * [Donut 3: how to defeat the hierarchical constraints](https://github.com/paypal/InnerSourceCommons/wiki/Donut-3%3A-how-to-defeat-the-hierarchical-constraints)
 * [Donut 4: modular code (for reuse) requires extra resources](https://github.com/paypal/InnerSourceCommons/wiki/Donut-4%3A-modular-code-%28for-reuse%29-requires-extra-resources)
@@ -70,15 +67,13 @@ Pattern Donuts (needing a solution)
 * [Get contributions despite silo thinking](https://github.com/paypal/InnerSourcePatterns/pull/38)
 
 
-Pattern Meta Info
-=================
+# Pattern Meta Info
 
 * [Pattern States](meta/pattern-states.md) - Definitions of the various states and review steps a pattern can be in
 * [Pattern Template](meta/pattern-template.md) - Start a new pattern with a copy of this
 
 
-Licensing
-=========
+# Licensing
 
 ![Creative Commons License](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)
 

meta/trusted-collaborators.md

@@ -1,23 +1,18 @@
 # Trusted Collaborators
 
-Trusted collaborators/contributors/committers (TC's) are those members of our community who we have explicitly added to our Github repository. 
-These people have elevated rights, allowing them to send in changes directly to branches and to accept Pull Requests.
+Trusted collaborators/contributors/committers (TC's) are those members of our community who we have explicitly added to our Github repository. These people have elevated rights, allowing them to send in changes directly to branches and to accept Pull Requests.
 
-We ask that TC's still adhere to the Pull-Request mechanism, unless they are making changes to documentation where it 
-is not realistic that anyone will review, or if there are easy typos/grammar fixes.
+We ask that TC's still adhere to the Pull-Request mechanism, unless they are making changes to documentation where it is not realistic that anyone will review, or if there are easy typos/grammar fixes.
 
 ## Who we add
 We add most people who send any sizable change. We work on trust - with great privilege comes great responsibility!
 
-Adding people off-the-bat encourages more contributions, displays trust, allows us to easily tag each other in reviews, 
-and ensures there is always someone around to moderate the site, move reviews along, and accept Pull Requests! 
-If anyone goes on vacation, there are a slew of others that could step in.
+Adding people off-the-bat encourages more contributions, displays trust, allows us to easily tag each other in reviews, and ensures there is always someone around to moderate the site, move reviews along, and accept Pull Requests! If anyone goes on vacation, there are a slew of others that could step in.
 
 If you want to become a Collaborator, @ mention one of the [Admins](#admins) in an Issue.
 
 ## Admins
-There are currently a handful of Github Admins for this repository. They hold the ability to add collaborators and modify 
-the repositories nuclear options (delete, rename, etc).
+There are currently a handful of Github Admins for this repository. They hold the ability to add collaborators and modify the repositories nuclear options (delete, rename, etc).
 
 * @nyeates - ask me first
 * @gruetter