exercism · kytrinyx · Nov 24, 2016 · Oct 20, 2016
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/docs/filing-a-bug-report.md b/docs/filing-a-bug-report.md
@@ -0,0 +1,68 @@
+# Writing an Actionable Bug Report
+
+We're a work in progress.  You reporting bugs in a clear and actionable format is a big help.  Thanks!!
+
+When writing a bug, please include:
+
+1. the steps you took to get to the defect (number the steps using a little markdown, as shown below).
+-  what you *expected* to happen after the last step.
+-  what *actually* happened after the last step.
+- information about your particular situation:
+  * if it's happening while you're using the CLI, include the **redacted** output of `exercism debug`.
+    * "redacted" meaning remove your API key from the output before including in the issue.
+  - if its' happening on the website, include your OS and browser versions.
+
+## Example
+
+    1. I recently completed the Hello World for Java. 
+    -  I submitted the file (I got the success message).
+    -  I went to the link provided by the CLI.
+       * **Expected:** to see my submission, 
+       * **Actual:** I got a 404.
+
+    Here's my "exercism debug":
+    ```
+    **** Debug Information ****
+    Exercism CLI Version: 2.3.0
+    Exercism CLI Latest Release: 2.3.0
+    OS/Architecture: darwin/amd64
+    Build OS/Architecture /
+    Home Dir: /Users/jtigger
+    Config file: /Users/jtigger/.exercism.json
+    API Key: *******
+    Exercises Directory: /Users/jtigger/workspace/exercism/exercises
+    Testing API endpoints reachability
+      * API: http://exercism.io [connected] 350.644953ms
+      * GitHub API: https://api.github.com/ [connected] 386.82533ms
+      * XAPI: http://x.exercism.io [connected] 796.511395ms
+    ```
+
+which formats to:
+
+-
+
+1. I recently completed the Hello World for Java. 
+-  I submitted the file (I got the success message).
+-  I went to the link provided by the CLI.
+   * **Expected:** to see my submission, 
+   * **Actual:** I got a 404.
+
+Here's my "exercism debug":
+```
+**** Debug Information ****
+Exercism CLI Version: 2.3.0
+Exercism CLI Latest Release: 2.3.0
+OS/Architecture: darwin/amd64
+Build OS/Architecture /
+Home Dir: /Users/jtigger
+Config file: /Users/jtigger/.exercism.json
+API Key: *******
+Exercises Directory: /Users/jtigger/workspace/exercism/exercises
+Testing API endpoints reachability
+  * API: http://exercism.io [connected] 350.644953ms
+  * GitHub API: https://api.github.com/ [connected] 386.82533ms
+  * XAPI: http://x.exercism.io [connected] 796.511395ms
+```
+
+-
+
diff --git a/docs/img/a-bug.png b/docs/img/a-bug.png
diff --git a/docs/img/an-idea.png b/docs/img/an-idea.png
diff --git a/docs/img/clipboard-and-gear.png b/docs/img/clipboard-and-gear.png
diff --git a/docs/img/computer-code.png b/docs/img/computer-code.png
diff --git a/docs/img/globe.png b/docs/img/globe.png
diff --git a/docs/img/gopher.png b/docs/img/gopher.png
diff --git a/docs/img/group-of-people.jpg b/docs/img/group-of-people.jpg
diff --git a/docs/img/mentoring.jpg b/docs/img/mentoring.jpg
diff --git a/docs/img/mortarboard.jpg b/docs/img/mortarboard.jpg
diff --git a/docs/img/prompt.png b/docs/img/prompt.png
diff --git a/docs/img/ruby.png b/docs/img/ruby.png
diff --git a/docs/img/screen-art.jpg b/docs/img/screen-art.jpg
diff --git a/docs/img/target-a-track.png b/docs/img/target-a-track.png
diff --git a/docs/img/volunteering-hand.png b/docs/img/volunteering-hand.png
diff --git a/docs/overview-of-exercism.md b/docs/overview-of-exercism.md
@@ -0,0 +1 @@
+*(This page needs to be written.  See [exercism/exercism.io#3253](https://github.com/exercism/exercism.io/issues/3253) for details.)*
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -0,0 +1,35 @@
+# Roadmap
+
+## Overview
+
+Development efforts at the moment focus on making the core experience good: 
+
+* smooth onboarding, 
+- rich conversations, 
+- high quality feedback, and 
+- getting feedback quickly.
+
+### Smooth Onboarding
+
+From quickly/concisely conveying what a programmer (of various stripes) would get from participating in Exercism, to the actual path from zero to submitted exercise on any given track, it can be bumpy.
+
+Let's hunt down bits of waste particularly along this path and flatten them: extraneous words and confusing flows should be substituted for clear instructions and intuitive/guided next steps.
+
+The root of these efforts focus on User Experience (UX).  The following are jumping-off points into those efforts.
+
+* call for help with UX in general: [exercism/discussions#34](https://github.com/exercism/discussions/issues/34).
+- conveying value and clear action on the homepage: [exercism/discussions#31](https://github.com/exercism/discussions/issues/31).
+
+### Rich Conversations
+
+Exercism is fundamentally a space that encourages programmers to talk about what's going on in their heads as they work and rework their code.  That thinking bit is the heart of how individuals can become better.
+
+What can we do to encourage more and richer conversations among Exercism users?
+
+
+
+
+- supporting common workflows in profile, dashboard, and account pages: [exercism/discussions#33](https://github.com/exercism/discussions/issues/33)
+- and the solutions page: [exercism/discussions#32](https://github.com/exercism/discussions/issues/32).
+
+
diff --git a/docs/setting-up-local-development.md b/docs/setting-up-local-development.md
@@ -0,0 +1 @@
+*(This page needs to be written.  See [exercism/exercism.io#3251](https://github.com/exercism/exercism.io/issues/3251) for details.)*
diff --git a/docs/the-contribution-workflow.md b/docs/the-contribution-workflow.md
@@ -0,0 +1 @@
+*(This page needs to be written.  See [exercism/exercism.io#3252](https://github.com/exercism/exercism.io/issues/3252) for details.)*
diff --git a/docs/the-exercism-way.md b/docs/the-exercism-way.md
@@ -0,0 +1,13 @@
+Please intend to help your fellow programmers improve.  There is a [time](http://proco.stanford.edu/) and [place](https://www.codewars.com/) for competition, it's not here.
+
+## Tips
+
+Here's a collection on easy-to-digest bits; pick one at random for inspiration in leaving constructive feedback on submissions:
+
+- Make your feedback more digestible: start by pointing out something you really liked about this submission.
+- Imagine this person is you when you first started in the language.
+- With each challenge, include a piece of support.
+- What if you framed your feedback as a question to encourage curiosity, rather than a correcting directive?
+- Consider leaving a praise-only comment on this one.
+- Imagine you're warmly welcoming someone to your country when introducing them to the idioms and ways-of-thinking of the language.
+- Empathize: is your feedback worded in a way that you could easily take?