diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 113cadb7a3..fa7eaf3265 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,250 @@ First of all, **thank you** for helping with Exercism.io! We are working to improve this document, and if you find any part of it confusing, or if you can't figure out how to get started with something, then rest assured it's not you, it's us! Please open up a new issue to describe what you were hoping to contribute with, and what you're wondering about, and we'll figure out together how to improve the documentation. +---- + +# Finding Your Way + +| [I see a problem](#i-see-a-problem) | [I have an idea](#i-have-an-idea) | [I would like to help](#i-would-like-to-help) | +|:---:|:---:|:---:| +|[![I see a problem](docs/img/a-bug.png)](#i-see-a-problem) | [![I have an idea](docs/img/an-idea.png)](#i-have-an-idea) | [![I would like to help](docs/img/volunteering-hand.png)](#i-would-like-to-help) | + +-- + +## I see a problem + +| [on the website](#i-see-a-problem-on-the-website) | [with the command-line client (CLI)](#i-see-a-problem-with-the-command-line-client-cli) | [getting started with a language](#i-see-a-problem-getting-started-with-a-language) | [with a specific exercise](#i-see-a-problem-with-a-specific-exercise) | +|:---:|:---:|:---:|:---:| +|[![I see a problem on the website](docs/img/globe.png)](#i-see-a-problem-on-the-website) | [![I see a problem with the CLI](docs/img/prompt.png)](#i-see-a-problem-with-the-command-line-client-cli) | [![I see a problem getting started with a language](docs/img/target-a-track.png)](#i-see-a-problem-getting-started-with-a-language) | [![I see a problem with a specific exercise](docs/img/computer-code.png)](#i-see-a-problem-with-a-specific-exercise) | + + +### I see a problem on the website + +* If you're having trouble figuring out how to do something on the website, jump in the [online support chat](https://gitter.im/exercism/support) and ask there. +- Check [`exercism/exercism.io`](https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3Abug)'s repo for bugs; and while we might know there's an issue, any additional details sometimes can help. +- If the website has a bug, you can help by [filing a bug report](docs/filing-a-bug-report.md) in the [`exercism/exercism.io` repository](https://github.com/exercism/exercism.io/issues/new). + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-know--want-to-get-better-at-web-programming). + +- + +### I see a problem with the command-line client (CLI) + +* If you're having trouble installing or working with the CLI, ask for help in our [online support chat](https://gitter.im/exercism/support). +- It may be a reported/known bug; check [`exercism/cli`](https://github.com/exercism/cli/issues?q=is%3Aissue+is%3Aopen+label%3Abug)'s repo for bugs. +- If the CLI has a bug, you can help by [filing a bug report](docs/filing-a-bug-report.md) in the [`exercism/cli` repository](https://github.com/exercism/cli/issues/new). + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-know--want-to-get-better-at-go). + +- + +### I see a problem getting started with a language + +* If you're having trouble with the setup instructions, ask for help in our [online support chat](https://gitter.im/exercism/support). +- If you see a problem with the setup instructions, you can help by [filing a bug report](docs/filing-a-bug-report.md) in the "Issues" section of the [corresponding language repository](http://exercism.io/repositories). + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-can--want-to-get-better-at-organizing-stuff). + +- + +### I see a problem with a specific exercise + +* If a particular exercise is giving you grief, ask for help in our [online support chat](https://gitter.im/exercism/support). +- If there's a defect in the... + - **instructions** of the exercise, you can make a difference by [filing a bug report](docs/filing-a-bug-report.md) in the [`exercism/x-common` repository](https://github.com/exercism/x-common/issues/new). + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-can--want-to-get-better-at-organizing-stuff). + - **tests** or **starter code** of the exercise, you can help by [filing a bug report](docs/filing-a-bug-report.md) in the "Issues" section of the [corresponding language repository](http://exercism.io/repositories). + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-am-fluent-in--want-to-get-better-at-a-particular-programming-language). +- You can ask for help within the track: + 1. `exercism submit` the code you have; + - Follow the link that the CLI returns to view your new submission on the website; + - In the "**Manage**" pull-down (top-right), select "**Request Help**". + + When you do this, your submission is highlighted, letting others know you're stuck. + +---- + +## I have an idea + + +| [making the website better](#i-have-an-idea-about-making-the-website-better) | [improving the command-line client (CLI)](#i-have-an-idea-about-improving-the-command-line-client-cli) | [a brand-new exercise for Exercism](#i-have-an-idea-about-a-brand-new-exercise-for-exercism) | [improving an existing exercise](#i-have-an-idea-about-improving-an-existing-exercise) | +|:---:|:---:|:---:|:---:| +|[![Making the website better](docs/img/globe.png)](#i-have-an-idea-about-making-the-website-better) | [![Improving the command-line client](docs/img/prompt.png)](#i-have-an-idea-about-improving-the-command-line-client-cli) | [![A brand new exercise for Exercism](docs/img/target-a-track.png)](#i-have-an-idea-about-a-brand-new-exercise-for-exercism) | [![Improving an existing exercise](docs/img/computer-code.png)](#i-have-an-idea-about-improving-an-existing-exercise) | + + +### I have an idea about making the website better + +Is it around a portion of the site we're currently talking about? Jump in! + +Current specific discussions: + +* User experience: [`exercism/discussions#34`](https://github.com/exercism/discussions/issues/34), +- solutions page: [`exercism/discussions#32`](https://github.com/exercism/discussions/issues/32), + + +Here are some helpful starter searches in the two repositories that contain ideas about the website: + +* the home page: [`exercism/discussions?homepage`](https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+homepage+sort%3Aupdated-desc) / [`exercism/exercism.io?homepage`](https://github.com/exercism/exercism.io/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20homepage+sort%3Aupdated-desc), +- user's dashboard: [`exercism/discussions?dashboard`](https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+dashboard+sort%3Aupdated-desc) / [`exercism/exercism.io?dashboard`](https://github.com/exercism/exercism.io/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20dashboard%20+sort%3Aupdated-desc), +- user's profile page: [`exercism/discussions?profile`](https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+profile+sort%3Aupdated-desc) / [`exercism/exercism.io?profile`](https://github.com/exercism/exercism.io/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20profile%20+sort%3Aupdated-desc), +- user's account page: [`exercism/discussions?account`](https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+account+sort%3Aupdated-desc) / [`exercism/exercism.io?account`](https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+account+sort%3Aupdated-desc). + +If the idea doesn't fit in one of those discussions, then if it relates to: + +* a specific part of the site, start a new conversation in the [`exercism/exercism.io`](https://github.com/exercism/exercism.io/issues/new) repository. +- multiple aspects of the site, kick it off in the [`exercism/discussions`](https://github.com/exercism/discussions/issues/new) repository. + +- + +### I have an idea about improving the command-line client (CLI) + +Current specific discussions: + +* Overall user experience with the CLI: [`exercism/discussions#35`](https://github.com/exercism/discussions/issues/35). + +Here are some helpful starter searches in the two repositories that contain ideas about the CLI: + +* [`exercism/cli?`](https://github.com/exercism/cli/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) +- [`exercism/discussions?cli`](https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+cli+sort%3Aupdated-desc) + +If the idea isn't being discussed yet, kick it off in the [`exercism/cli`](https://github.com/exercism/cli/issues/new) repository. + +- + +### I have an idea about a brand-new exercise for Exercism + +New exercise ideas are definitely welcome! Here's how to ensure the idea lands in the right place: + +*Note: the central library of exercises on Exercism is https://github.com/exercism/x-common.* + +- Check to see if the exercise is listed: https://github.com/exercism/x-common/tree/master/exercises. + - If it is there, but not in the language you'd like to solve it in, put in a request in that particular language's repository: http://exercism.io/repositories. + - if you have the time and the desire, you can help *even more* by [implementing it](#-fluency-in-a-particular-programming-language). + - If it is not there, suggest it in [`exercism/x-common`](https://github.com/exercism/x-common/issues/new). + - if you have the time and the desire, you can help *even more* by [implementing it](https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#implementing-a-completely-new-exercise). +- If you know of a good source of potential new problems, please share: [`exercism/x-common#107`](https://github.com/exercism/x-common/issues/107). + +- + +### I have an idea about improving an existing exercise + +- If the idea is to improve the... + - **instructions** of the exercise, you can make a difference by making the suggestion in the [`exercism/x-common`](https://github.com/exercism/x-common/issues/new) repository. + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-can--want-to-get-better-at-organizing-stuff). + - **tests** or **starter code** of the exercise, you can help by making the suggestion in the "Issues" section of the [corresponding language repository](http://exercism.io/repositories). + - if you have the time and the desire, you can help *even more* by [fixing it](#i-would-like-to-help-i-am-fluent-in--want-to-get-better-at-a-particular-programming-language). + + +---- + + +## I would like to help + +Thank you! + +You have (or want to improve your) skills in + +| [technical writing and organization](#i-would-like-to-help-i-can--want-to-get-better-at-technical-writing-and-organization) | [fluency in a particular programming language](#i-would-like-to-help-i-am-fluent-in--want-to-get-better-at-a-particular-programming-language) | [web programming](#i-would-like-to-help-i-know--want-to-get-better-at-web-programming) | [Ruby on Rails](#i-would-like-to-help-i-know--want-to-get-better-at-ruby-on-rails) | [Go](#i-would-like-to-help-i-know--want-to-get-better-at-go) | [web design](#i-would-like-to-help-i-know--want-to-get-better-at-web-design) | [mentoring others](#i-would-like-to-help-i-know--want-to-get-better-at-mentoring-others) +|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| [![organizing stuff](docs/img/clipboard-and-gear.png)](#i-would-like-to-help-i-can--want-to-get-better-at-technical-writing-and-organization) | [![fluency in a particular programming language](docs/img/mortarboard.jpg)](#i-would-like-to-help-i-am-fluent-in--want-to-get-better-at-a-particular-programming-language) | [![web programming](docs/img/globe.png)](#i-would-like-to-help-i-know--want-to-get-better-at-web-programming) | [![Ruby on Rails](docs/img/ruby.png)](#i-would-like-to-help-i-know--want-to-get-better-at-ruby-on-rails) | [![Go](docs/img/gopher.png)](#i-would-like-to-help-i-know--want-to-get-better-at-go) | [![web design](docs/img/screen-art.jpg)](#i-would-like-to-help-i-know--want-to-get-better-at-web-design) | [![mentoring others](docs/img/mentoring.jpg)](#i-would-like-to-help-i-know--want-to-get-better-at-mentoring-others) + +### I would like to help; I can / want to get better at technical writing and organization + +- Find discussions about ways we'd like to improve our documentation: [`exercism/discussions?documentation`](https://github.com/exercism/discussions/issues?q=is%3Aissue+is%3Aopen+documentation+sort%3Aupdated-desc) +- Help make the instructions of an exercise more clear, interesting and/or engaging by locating that exercise in [`exercism/x-common`](https://github.com/exercism/x-common/tree/master/exercises) and [Tweaking its README.md](https://github.com/exercism/x-common/blob/master/CONTRIBUTING.md#tweaking-a-readme). +- Issues across all of Exercism looking for help with documentation: [`exercism?documentation`](https://github.com/search?o=desc&p=1&q=org%3Aexercism+documentation+is%3Aissue&ref=searchresults&s=updated&state=open&type=Issues&utf8=%E2%9C%93) + +- + +### I would like to help; I am fluent in / want to get better at a particular programming language + +Are you a language enthusiast? Help other people fall in love with your language by... + +#### Mentoring Others + +- Give feedback on other's submissions in your [Activity Stream](http://exercism.io/inbox). +- Help others get unstuck in the [support chat](https://gitter.im/exercism/support). +- However you support others, aim to do it [The Exercism Way](docs/the-exercism-way.md). + +#### Contributing to a Language Track + +This means helping maintain the code of the exercises and supporting tooling for a particular language. + +- Find a language you love or want to get to know better: http://exercism.io/repositories +- Orient yourself through our [Getting Involved in a Track] (docs/getting-involved-in-a-track.md) guide. + +- + +### I would like to help; I know / want to get better at web programming + +Do you have/want to have chops in HTML+CSS+JavaScript/CoffeeScript and want to improve the feel and function of the Exercism website? + +1. [Setup your local development environment](docs/setting-up-local-development.md). +- Locate an feature/bug to work on: + - [`exercism/exercism.io?label:good first patch`](https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+patch%22) + - [`exercism/exercism.io?label:bug`](https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3Abug) +- Work the issue: [the contribution workflow](docs/the-contribution-workflow.md). + +You may also find these helpful: + +- [Architecture Overview of Exercism](docs/overview-of-exercism.md) + + +- + +### I would like to help; I know / want to get better at Ruby on Rails + +Do you have/want to have chops in Ruby and Sinatra or Ruby on Rails and want to add to the website? + +1. [Setup your local development environment](docs/setting-up-local-development.md). +- Locate an feature/bug to work on: + - [`exercism/exercism.io?label:good first patch`](https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+patch%22) + - [`exercism/exercism.io?label:bug`](https://github.com/exercism/exercism.io/issues?q=is%3Aissue+is%3Aopen+label%3Abug) +- Work the issue: [the contribution workflow](docs/the-contribution-workflow.md). + +You may also find these helpful: + +- [Architecture Overview of Exercism](docs/overview-of-exercism.md) + + +- + + +### I would like to help; I know / want to get better at Go + +One of the more subtle but important parts of the Exercism experience is our CLI; it's written in Go. + +1. Setup your local development environment for the CLI: [`exercism/cli`](https://github.com/exercism/cli). +- Locate an feature/bug to work on: [`exercism/cli?`](https://github.com/exercism/cli/issues) +- Work the issue: [the contribution workflow](docs/the-contribution-workflow.md). + +You may also find these helpful: + +- [Architecture Overview of Exercism](docs/overview-of-exercism.md) + + +- + +### I would like to help; I know / want to get better at web design + +Do you love making enticing user experiences? Help us [rethink our user experience](https://github.com/exercism/discussions/issues/34) (UX)! + +* the [profile](https://github.com/exercism/discussions/search?q=profile&state=open&type=Issues) or [account](https://github.com/exercism/discussions/search?q=account&state=open&type=Issues) pages. +- the [dashboard](https://github.com/exercism/discussions/search?q=dashboard&state=open&type=Issues). +- the [homepage](https://github.com/exercism/discussions/search?q=homepage&state=open&type=Issues). +- the [solutions page](https://github.com/exercism/discussions/issues/32). + +- + +### I would like to help; I know / want to get better at mentoring others + +Do you like mentoring people? + +* Hang out in the support chat [support chat](https://gitter.im/exercism/support), or +* submit an exercise so you can [give feedback to people who have submitted it, too](http://exercism.io/inbox). + + +---- + +# Table of Contents + * [Code of Conduct](#code-of-conduct) * [The Ecosystem](#the-ecosystem) * [Get Set Up](#setup) @@ -504,9 +748,7 @@ X is a collection of scripts to organize and compile documentation for the many ## Future Roadmap -The focus of the development efforts at the moment are about making the core -experience good: smooth onboarding, rich conversations, high quality feedback, -and getting feedback quickly. +We focus our efforts on the [roadmap](docs/roadmap.md). Sometimes we get suggestions for things that would be great, but they're not part of locking down the core behavior of the app. In this case we'll close diff --git a/docs/filing-a-bug-report.md b/docs/filing-a-bug-report.md new file mode 100644 index 0000000000..57912de736 --- /dev/null +++ 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 new file mode 100644 index 0000000000..6918ddf6f0 Binary files /dev/null and b/docs/img/a-bug.png differ diff --git a/docs/img/an-idea.png b/docs/img/an-idea.png new file mode 100644 index 0000000000..47344b71b0 Binary files /dev/null and b/docs/img/an-idea.png differ diff --git a/docs/img/clipboard-and-gear.png b/docs/img/clipboard-and-gear.png new file mode 100644 index 0000000000..0f26cb3714 Binary files /dev/null and b/docs/img/clipboard-and-gear.png differ diff --git a/docs/img/computer-code.png b/docs/img/computer-code.png new file mode 100644 index 0000000000..00c8b288e8 Binary files /dev/null and b/docs/img/computer-code.png differ diff --git a/docs/img/globe.png b/docs/img/globe.png new file mode 100644 index 0000000000..c08c59ad07 Binary files /dev/null and b/docs/img/globe.png differ diff --git a/docs/img/gopher.png b/docs/img/gopher.png new file mode 100644 index 0000000000..718d1e038b Binary files /dev/null and b/docs/img/gopher.png differ diff --git a/docs/img/group-of-people.jpg b/docs/img/group-of-people.jpg new file mode 100644 index 0000000000..ac6a1b1091 Binary files /dev/null and b/docs/img/group-of-people.jpg differ diff --git a/docs/img/mentoring.jpg b/docs/img/mentoring.jpg new file mode 100644 index 0000000000..e887366d9f Binary files /dev/null and b/docs/img/mentoring.jpg differ diff --git a/docs/img/mortarboard.jpg b/docs/img/mortarboard.jpg new file mode 100644 index 0000000000..4d34c13bad Binary files /dev/null and b/docs/img/mortarboard.jpg differ diff --git a/docs/img/prompt.png b/docs/img/prompt.png new file mode 100644 index 0000000000..80d1878c13 Binary files /dev/null and b/docs/img/prompt.png differ diff --git a/docs/img/ruby.png b/docs/img/ruby.png new file mode 100644 index 0000000000..6f7fad21cd Binary files /dev/null and b/docs/img/ruby.png differ diff --git a/docs/img/screen-art.jpg b/docs/img/screen-art.jpg new file mode 100644 index 0000000000..418f8ce106 Binary files /dev/null and b/docs/img/screen-art.jpg differ diff --git a/docs/img/target-a-track.png b/docs/img/target-a-track.png new file mode 100644 index 0000000000..5103fa0108 Binary files /dev/null and b/docs/img/target-a-track.png differ diff --git a/docs/img/volunteering-hand.png b/docs/img/volunteering-hand.png new file mode 100644 index 0000000000..a1b49f1bdf Binary files /dev/null and b/docs/img/volunteering-hand.png differ diff --git a/docs/overview-of-exercism.md b/docs/overview-of-exercism.md new file mode 100644 index 0000000000..61aec8f892 --- /dev/null +++ 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 new file mode 100644 index 0000000000..12a46f4baf --- /dev/null +++ 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 new file mode 100644 index 0000000000..a032c266de --- /dev/null +++ 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 new file mode 100644 index 0000000000..f4b369ef37 --- /dev/null +++ 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 new file mode 100644 index 0000000000..d266c086ce --- /dev/null +++ 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?