Merge branch 'contributing-revamp'

Author: nyeates

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # How to Contribute
 
-First, checkout our complete list of patterns: [Google Doc](https://docs.google.com/spreadsheets/d/17KPZdCoquTnYSj03pX4v2vn8lrSYO_6HK20u1cwaLPg/edit#gid=0) OR [public GitHub](https://github.com/paypal/InnerSourcePatterns#reviewed-patterns-proven-and-reviewed)
+First, checkout our complete list of patterns: [public GitHub](https://github.com/paypal/InnerSourcePatterns#reviewed-patterns-proven-and-reviewed) OR [Google Doc](https://docs.google.com/spreadsheets/d/17KPZdCoquTnYSj03pX4v2vn8lrSYO_6HK20u1cwaLPg/edit#gid=0)
 
 We encourage beginners seeking answers to jump in by creating `donut` patterns (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). 
 
@@ -18,21 +18,21 @@ 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](#b-discussing-early-ideas-in-issues).
+The below steps can be used to create a new pattern. The use-case here is that you have an 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:
+The simplest way to create a pattern is with your browser (see below).  
+[Like the command-line better? See here for alternate instructions.](/meta/technical-git-howto.md)
 
-1. Assure you are logged into GitHub & go to the [patterns web repo](https://github.com/paypal/InnerSourcePatterns)
-2. Click on the 'Create new file' button
-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) below.
-6. Propose this new file and then also create a Pull Request (PR)
+![Creating a new pattern](/assets/img/write-new-pattern.png)
 
-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).
+1. Login to GitHub & inside the [patterns web repo](https://github.com/paypal/InnerSourcePatterns), click on the 'Create new file' button
+2. Name the file like this example: "project-management-time-pressures.md"
+3. 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 fledgling pattern; it does not need to be complete, as you can add to it later
+4. 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) below.
+5. Propose this new file and then also create a Pull Request (PR)
 
-Like the command-line better? *As an alternative, you can utilize git's native command line instead*. [We have a separate set of technical instructions here](/meta/technical-git-howto.md).
+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 Review process. See next steps in [Interacting with Pattern Reviews](#c-interacting-with-patterns-reviews).
 
 
 ## Use Branches When Creating New Patterns
@@ -49,34 +49,41 @@ If you are asked to 'Commit directly...' vs 'Create a new branch...'
 
 # B. Discussing Early Ideas in Issues
 
-If you feel that you need extra advice when dealing with patterns, please open an issue in the [ticketing system](https://github.com/paypal/InnerSourcePatterns/issues). This process is only needed when contributing early ideas that you are uncertain about. 
+If you feel that you need extra advice when dealing with patterns, please [open an issue](https://github.com/paypal/InnerSourcePatterns/issues). This process is only needed when contributing early ideas that you are uncertain about. 
 
 Here are tips on starting this discussion:
 
-* [Create a new ticket](https://github.com/paypal/InnerSourcePatterns/issues/new).
-* Add a concise title like this example: "pattern/badly-named-piles"
-* Describe your problem. Think about the context of your problem and your expected output. Where do you see this problem most? What is the setup of your business and organization? Do you have opinions/ideas on what causes or leads-to the problem?
+* [Create a new ticket](https://github.com/paypal/InnerSourcePatterns/issues/new), add a concise title, and describe your problem. Think about the context of your problem and your expected output. Where do you see this problem most? What is the setup of your business and organization? Do you have opinions/ideas on what causes or leads-to the problem?
 * Ask any questions that you are unsure about. Are you unsure if this problem belongs here? Are you unsure on how to frame and explain the problem?
-* [Apply the label](https://help.github.com/articles/applying-labels-to-issues-and-pull-requests/) `Idea`. Labels can be found in the right column settings.
+* [Apply the label](https://help.github.com/articles/applying-labels-to-issues-and-pull-requests/) `Early Idea`. Labels can be found in the right column settings.
 
-After this process, it is our turn to drive you through the pattern creation process. We will help to land your idea and check if there are existing  similar patterns.
+After this process, it is our turn to drive you through the pattern creation process. We will help to land your idea and check if there are existing similar patterns.
 
 
 
 # C. Interacting with Patterns Reviews
 
-A pattern is said to be "in-review" or being "Reviewed" when we have a Pull Request with some amount of Pattern detail filled out. We then communally review, and comment-on, and OK these "in-review" patterns. There are multiple steps involved, sometimes requiring multiple re-writes, and peer-reviews. Usually though, we first look for a pattern with all the fields filled out, and then go through TWO peer-reviews.
+A pattern is said to be "in-review" or being "Reviewed" when we have a Pull Request with some amount of Pattern detail filled out. We then communally review, and comment-on, and OK these "in-review" patterns. Usually, we first look for a pattern with all the fields filled out, and then go through TWO peer-reviews.
 
-Our workflow is done through Pull Requests (PR's) and Branches. Branches are meant to separate content, so that multiple people and patterns can exist all at once. Pull Requests (PR's) are used to bring online discussion/review about a specific Inner Source pattern. 
+## Editing a pattern that is in-review
+Go ahead, edit away - we can always go back - and we encourage action over discussion.
 
-FIXME Explain how to add content to in-review patterns. Explain how to add review comments and accepting a review.
+![How to edit an existing pattern](/assets/img/edit-existing-pattern.png)
 
-Below are the major steps in our Review process:
+## Reviewing a pattern
+FIXME Explain how to add review comments and accepting a review. Basically, this is all done through Githubs web GUI around Pull Requests.
 
-1. Label your Pull Request with `pattern`. Additionally decide whether to label it with `idea`, `donut`, or `draft` and `Ready for Review` or `Incomplete`
-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.
+FIXME Give tips for good reviews. We have done both interspersed comments, or pattern-wide advise. Be constructive. If you can fix the problem, [edit the PR](#editing-a-pattern-that-is-in-review) instead of leaving a comment.
 
+## Our Review Process
+Below are the procedural steps in our Review process:
+
+1. Decide which Maturity level your pattern is in: `Donut (Lacks solution)`, `Unproven`, or `Proven`; these all describe what state the *Solution* is in.
+2. Decide which Review Step you are in: Usually `Incomplete` or `Do 1st Review`
+3. Reviewers can now use the PR features to comment on the pattern.
+4. In most cases, we do two reviews, and the PR's labels should reflect `Do 2nd Review` etc.
+5. After reviews are complete, the reviewers or author should Revise and Finalize the pattern, eventually labeling it with  `Accepted`.
+6. 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.
+
+## Completed Patterns
 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).

assets/img/edit-existing-pattern.png

@@ -1,14 +1,17 @@
 # What is Markdown?
 
-A markdown file is a plain ASCII text file that is meant to be easy to read in plaintext, while also being pretty once rendered. 
-It is similar to the format that many wiki's have. As an example, you can see 
-[this rendered pattern](https://github.com/paypal/InnerSourcePatterns/blob/master/dedicated-community-leader.md) 
-of ours also [in plain text](https://raw.githubusercontent.com/paypal/InnerSourcePatterns/master/dedicated-community-leader.md). 
-You can do this for any markdown file by clicking the ``Raw`` button when viewing a file online.
+A markdown file is a plain ASCII text file that is meant to be easy to read in plaintext, while also being pretty once rendered.
+
+It is similar to the format that many wiki's have. As an example, you can see [this rendered pattern](https://github.com/paypal/InnerSourcePatterns/blob/master/dedicated-community-leader.md) of ours also [in plain text](https://raw.githubusercontent.com/paypal/InnerSourcePatterns/master/dedicated-community-leader.md). You can do this for any markdown file by clicking the ``Raw`` button when viewing a file online.
 
 The ASCII is marked up in a standard format. Here are two cheatsheets for that format:
 
 * https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf
 * https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
 
+You can test your markdown on these online "live" editors:
+
+* http://socrates.io/
+* https://jbt.github.io/markdown-editor/
+
 If you have content in Word or Google docs, you can simply copy the existing text and paste it in to plain text, and then modify the titles and bullets to be in markdown format. There might be a converter.