diff --git a/.github/markdownlint.json b/.github/markdownlint.json new file mode 100644 index 000000000..1e765d9b7 --- /dev/null +++ b/.github/markdownlint.json @@ -0,0 +1,6 @@ +{ + "default": false, + "heading-increment": true, + "first-line-heading": true, + "heading-style": "atx" +} diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 000000000..d8d73610d --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,28 @@ +name: CI + +on: + push: + paths: + - "**.md" + branches: + - "main" + pull_request: + paths: + - "**.md" + branches: + - "main" + +jobs: + mdlint: + name: Lint Markdown + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # 2.3.4 + + - name: Run markdownlint + uses: nosborn/github-action-markdown-cli@9fc95163471d6460c35cccad13645912aaa25d5f # 1.1.1 + with: + files: "." + config_file: ".github/markdownlint.json" + ignore_files: "analyzer-comments/*" diff --git a/licences/cc_sa_4.md b/licences/cc_sa_4.txt similarity index 100% rename from licences/cc_sa_4.md rename to licences/cc_sa_4.txt diff --git a/licences/mit.md b/licences/mit.md index 36fe53393..e72cc1335 100644 --- a/licences/mit.md +++ b/licences/mit.md @@ -1,3 +1,5 @@ +# MIT Licence + Copyright 2019 Exercism Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: diff --git a/pages/about.md b/pages/about.md index 2badc74cb..d687671b7 100644 --- a/pages/about.md +++ b/pages/about.md @@ -1,4 +1,5 @@ -### What is Exercism? +# About Exercism +## What is Exercism? Exercism is an online platform designed to help you improve your coding skills through practice and mentorship. @@ -12,6 +13,6 @@ Exercism is designed to be fun and friendly, and we place a strong emphasis on e Sign up and have fun. Exercism is 100% free :) -### Who owns and runs Exercism? +## Who owns and runs Exercism? Exercism is a not-for-profit company. It is legally based in the United Kingdom, with Company Registration Number [11733062](https://beta.companieshouse.gov.uk/company/11733062). It is "company limited by guarantee" which means there are no shareholders, and no individuals "own" the company. Instead, the company has trustees who are responsible for ensuring it meets its aims and objectives. The current trustees are Katrina Owen and Jeremy Walker, who are also the company's Directors. diff --git a/pages/about_v1_to_v2.md b/pages/about_v1_to_v2.md index c76be1bba..f1b0c201e 100644 --- a/pages/about_v1_to_v2.md +++ b/pages/about_v1_to_v2.md @@ -1,10 +1,12 @@ +# About v1 to v2 transition + We've rebuilt Exercism from the ground up to provide a smoother, more in-depth experience. Exercism now has progression through tracks, more structured mentoring and a much better user interface. Below, we have outlined a few of the biggest changes. For even **more** details you can view [this document](https://github.com/exercism/v2-feedback). If you need help migrating solutions on your local system from v1 to v2, please [read this document](/cli-v1-to-v2). We are still working through lots of TODOs to get things right, so please bear with us, but we hope you find this new version more fun and useful than ever. -### New branding +## New branding There are aspects of the old logo and branding that we like, but we found that it doesn't express the most important thing about Exercism: this is a friendly, welcoming place focused on the humans. @@ -16,7 +18,7 @@ We want to emphasize human connections and a supportive, friendly learning envir To this end we have designed a completely new logo, and a new design aesthetic. -### Redesigned language tracks +## Redesigned language tracks We have completely redesigned the experience around joining, participating in, and completing a language track. @@ -49,7 +51,7 @@ Notice that we're not focusing on "artisans" as a core audience for the exercise That said, we believe that Exercism has a lot to offer artisans, and they are part of our core "mentor" audience, described in more detail below. -### A new mentorship model +## A new mentorship model Because learning can be such a vulnerable process, we decided after much deliberation to make the mentorship process private between the learner and their mentors. There are some giant trade-offs inherent in this choice, between helping people feel safe and supported, scaling mentorship, and making solutions available for others to learn from. We will be addressing some aspects of the old model of communal feedback and learning with the new teams interface. We have written in depth about the considerations we wrestled with and that led to this decision in the design document about code review. @@ -62,7 +64,7 @@ In order to reduce the risk of learners feeling like they're at the bottom of a Once a student has completed an exercise, they can decide whether or not to make it available to the broader Exercism community. If someone decides to make the solution available, they can also decide whether or not to include it in their public showcase. -### Privacy features +## Privacy features **Aliases:** People can choose on a track-by-track basis what avatar they want to use and what handle they want to go by. This means that people can use their Exercism username publicly in some tracks while remaining private in others. Logging in is now decoupled from GitHub, so the Exercism username may or may not be the same as their GitHub username. If someone chooses to use a handle that is different from their username, then we will make it clear to mentors that this is an alias. **Blocking:** People can choose to not interact with certain others. This goes for both learners who can opt out of certain mentors, and mentors who can choose to not work with certain learners. There are a number of reasons why people might want to not interact with someone, and they do not all reflect poorly on the person in question. We will however, be monitoring this data for outliers so that we can intervene if we are seeing behavior that is concerning. diff --git a/pages/automated_solution_analysis.md b/pages/automated_solution_analysis.md index 10a14be9b..29f7c30e0 100644 --- a/pages/automated_solution_analysis.md +++ b/pages/automated_solution_analysis.md @@ -1,8 +1,9 @@ -### What is it? +# Autoamted Solution Analysis +## What is it? We algorithmically analyse solutions to certain exercises to look for optimal solutions, which we can then instantly approve allowing students to move on to the next exercise without delay. -### How does it work? +## How does it work? We use a mixture of techniques to analyze solutions, but most centre around statically analysing the code that students submit. Each language has a different analyzer maintained by a different team, who may approach things in different ways. You may be interested in browsing the code to see how this works: - [C#](https://github.com/exercism/csharp-analyzer) diff --git a/pages/become_a_maintainer.md b/pages/become_a_maintainer.md index 4e28c4a54..cd9ba3cc8 100644 --- a/pages/become_a_maintainer.md +++ b/pages/become_a_maintainer.md @@ -1,12 +1,4 @@ -[tracks]: https://exercism.io/tracks -[repositories]: https://github.com/exercism -[triaging-issues]: https://github.com/exercism/docs/blob/master/you-can-help/triage-issues.md -[reviewing-prs]: https://github.com/exercism/docs/blob/master/you-can-help/review-pull-requests.md -[porting]: https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md -[problem-specifications]: https://github.com/exercism/problem-specifications -[blazon]: https://github.com/exercism/blazon -[blazon-process]: https://github.com/exercism/docs/blob/master/you-can-help/improve-exercise-metadata.md -[fixing-readmes]: https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/readmes.md +# Become a maintainer The Exercism language tracks are a great way to get involved in: @@ -148,3 +140,13 @@ hard to figure out how to solve it anyway. In this case consider whether there's a blog post or some documentation that you could point people to, and add it to `$ROOT/exercises/$SLUG/.meta/hints.md` in the exercise directory in the language track. If the file doesn't exist, create a new one. + +[tracks]: https://exercism.io/tracks +[repositories]: https://github.com/exercism +[triaging-issues]: https://github.com/exercism/docs/blob/master/you-can-help/triage-issues.md +[reviewing-prs]: https://github.com/exercism/docs/blob/master/you-can-help/review-pull-requests.md +[porting]: https://github.com/exercism/docs/blob/master/you-can-help/implement-an-exercise-from-specification.md +[problem-specifications]: https://github.com/exercism/problem-specifications +[blazon]: https://github.com/exercism/blazon +[blazon-process]: https://github.com/exercism/docs/blob/master/you-can-help/improve-exercise-metadata.md +[fixing-readmes]: https://github.com/exercism/docs/blob/master/language-tracks/exercises/anatomy/readmes.md diff --git a/pages/changelog.md b/pages/changelog.md index dd9c15302..038a1d179 100644 --- a/pages/changelog.md +++ b/pages/changelog.md @@ -1,53 +1,55 @@ -### [Website]- Add ability to change which solutions are published: +# Changelog + +## [Website]- Add ability to change which solutions are published: Previously, you could not change which solutions are published. We have now enabled this along with the ability to choose which appear on the profile and which allow public comments. [#4163](https://github.com/exercism/exercism/issues/4163) -### [Website] Add communal mentoring notes +## [Website] Add communal mentoring notes We have exposed the communal mentoring notes from GitHub to be visible directly within the UI. -### [Teams] Launch the site +## [Teams] Launch the site We have built a dedicated site for teams. It allows groups of people to complete exercises and mentor each other in a private space. We envision it being used by bootcamps, groups of friends, and colleagues at work. -### [Website] Delete my account +## [Website] Delete my account We needed to give people the ability to delete their account without emailing Jeremy. -### [Website] Reset CLI token +## [Website] Reset CLI token We wanted to let people reset their CLI tokens in case they are leaked. [#4150](https://github.com/exercism/exercism/issues/4150) -### [Website] Improve experience of "Legacy" or "Practice" solutions in Mentored Mode +## [Website] Improve experience of "Legacy" or "Practice" solutions in Mentored Mode Have separate restricted queues for core and side exercises when importing solutions created in v1 or in Practice Mode. -### [Website] Make side-exercise mentoring opt-in: +## [Website] Make side-exercise mentoring opt-in: At the moment some tracks have thousands of side-exercises in the backlog. We're going to change this behaviour so people have to opt-in to mentoring on an exercise-by-exercise basis and can only request mentoring on a handful of exercises at once. -### [Website] Put challenge back to mentor queue if mentor leaves conversation: +## [Website] Put challenge back to mentor queue if mentor leaves conversation: [#4308](https://github.com/exercism/exercism/issues/4308) -### [Website] Merge mentoring.exercism.io into the main site +## [Website] Merge mentoring.exercism.io into the main site We wanted to streamline the sign up process, to remove the Google Form and the need to join slack to mentor. This is the first step in a long list of changes we'll make to the mentoring onboarding process. -### [Website] Make the site responsive. +## [Website] Make the site responsive. The Exercism website is now mobile-responsive thanks to this [huge Pull Request](https://github.com/exercism/website/pull/252) by [@jackhughesweb](https://github.com/jackhughesweb).. -### [Website] Add all notifications +## [Website] Add all notifications Marked a notification as read but want to still see it? We've added a button for "All notifications" that allows you to see both read and unread notifications. Credit to [@PatrickMcSweeny](https://github.com/PatrickMcSweeny). -### [Website] Comments auto-save as typed +## [Website] Comments auto-save as typed Nothing is more frustrating than losing your work. To stop accidental tab-closes or refreshes, we've added autosaving as you type comments. Simply go back to the page and you'll find your text is still there!. Credit to [@jackhughesweb](https://github.com/jackhughesweb). -### [Website] Added Dark Theme to the code editor +## [Website] Added Dark Theme to the code editor We have added a dark theme to the code editor. You can enable it in [your preferences](https://exercism.io/my/settings/preferences/edit). Credit to [@jackhughesweb](https://github.com/jackhughesweb). -### [Tracks] Merged the Javascript and ECMAScript tracks +## [Tracks] Merged the Javascript and ECMAScript tracks We merged the Javascript and ECMAScript tracks with the aim of focussing the work of the maintainers and mentors into one place, and improve the quality of our offering. diff --git a/pages/cli.md b/pages/cli.md index 36aff03c3..8a5df4da5 100644 --- a/pages/cli.md +++ b/pages/cli.md @@ -1,29 +1,31 @@ -### Installation +# CLI + +## Installation The Exercism command line interface (CLI) is a tool that can download exercises, show your progress through a track, and submit your solutions - all from within your terminal. The best way to get started with the CLI is our [Interactive Walkthrough](https://exercism.io/cli-walkthrough). It guides you down the right path depending on your operating system, experience with the command line, etc, and will get your CLI configured. If you just want to download the CLI manually and work out how to use it, you can download and install it from [GitHub](https://github.com/exercism/cli/releases/latest). However, please note that we ask that you work through the [Interactive Walkthrough](https://exercism.io/cli-walkthrough) before opening any support requests. -### Upgrading from pre-v3 +## Upgrading from pre-v3 If you have a previous version of the CLI and want to upgrade, please read [these instructions](https://github.com/exercism/website-copy/blob/master/pages/cli_v1_to_v2.md). -### Basic usage +## Basic usage Run the help subcommand to get the full list of available commands. ```bash exercism help ``` -### Configuration +## Configuration You need to tell the tool who you are. You can find your token in your [settings page](http://exercism.io/my/settings). ``` exercism configure --token=YOUR_API_TOKEN ``` -### Troubleshooting +## Troubleshooting Make sure you are on the latest version. diff --git a/pages/cli_v1_to_v2.md b/pages/cli_v1_to_v2.md index 678b37b2a..9c04071b8 100644 --- a/pages/cli_v1_to_v2.md +++ b/pages/cli_v1_to_v2.md @@ -1,3 +1,5 @@ +# CLI v1 to v2 + If you haven't installed the new version of the command-line client (v3.x), please download the [latest release](https://github.com/exercism/cli/releases/latest). We recommend using our [interactive walkthrough](https://exercism.io/cli-walkthrough) to guide you through the installation and configuration process. The CLI for Windows is broken for versions prior to 3.0.5. diff --git a/pages/code_of_conduct.md b/pages/code_of_conduct.md index b4197c3eb..0f1d20bda 100644 --- a/pages/code_of_conduct.md +++ b/pages/code_of_conduct.md @@ -1,12 +1,14 @@ -### Introduction +# Code of Conduct + +## Introduction Exercism is a platform centered around empathetic conversation. We have a low tolerance for communication that makes anyone feel unwelcome, unsupported, insulted or discriminated against. -### Seen or experienced something uncomfortable? +## Seen or experienced something uncomfortable? If you see or experience abuse, harassment, discrimination, or feel unsafe or upset, please email abuse@exercism.io. We will take your report seriously. -### Enforcement +## Enforcement We actively monitor for Code of Conduct (CoC) violations and take any reports of violations extremely seriously. We have banned contributors, mentors and users due to violations. @@ -14,7 +16,7 @@ After we receive a report of a CoC violation, we view that person's conversation Exercism's leadership reserve the right to take whatever action they feel appropriate with regards to CoC violations. -### The simple version +## The simple version - Be empathetic - Be welcoming @@ -23,7 +25,7 @@ Exercism's leadership reserve the right to take whatever action they feel approp - Be supportive - Be polite -### The details +## The details Exercism should be a safe place for everybody regardless of - Gender, gender identity or gender expression @@ -72,7 +74,7 @@ If you say something that is found offensive, and you are called out on it, try - Ask for tips / help with avoiding making the offence in the future. - Apologise and ask forgiveness. -### History +## History This policy was initially adopted from the Front-end London Slack community and has been modified since. A version history can be seen on [GitHub](https://github.com/exercism/website-copy/edit/master/pages/code_of_conduct.md). diff --git a/pages/contact.md b/pages/contact.md index e9c7f3719..1290b4129 100644 --- a/pages/contact.md +++ b/pages/contact.md @@ -1,5 +1,7 @@ +# Contact Us + The best place to get help with Exercism is on Github at [https://github.com/exercism/exercism](https://github.com/exercism/exercism). You are welcome to open issues for support requests, ask questions, suggest features, or anything else there. If you'd like to get in touch privately please email us at [hello@exercism.io](mailto:hello@exercism.io), but please note that due to the quantity of emails we get we may not reply if the question would be more appropriate on GitHub. -If you have a Code of Conduct violation to report, please email us at [abuse@exercism.io](mailto:abuse@exercism.io) and include `[CoC]` in the subject line. We will deal with all CoC issues as a priority. \ No newline at end of file +If you have a Code of Conduct violation to report, please email us at [abuse@exercism.io](mailto:abuse@exercism.io) and include `[CoC]` in the subject line. We will deal with all CoC issues as a priority. diff --git a/pages/contribute.md b/pages/contribute.md index 25d483f1c..cc029767d 100644 --- a/pages/contribute.md +++ b/pages/contribute.md @@ -1,3 +1,5 @@ +# Contribute + We're really excited and grateful that you want to help with Exercism. There are three main ways to contribute to Exercism: diff --git a/pages/faqs.md b/pages/faqs.md index 67ecf05dc..a3f47ef67 100644 --- a/pages/faqs.md +++ b/pages/faqs.md @@ -1,13 +1,13 @@ -## Exercism FAQs +# FAQs -### Who is behind Exercism? +## Who is behind Exercism? Exercism was originally founded by [Katrina Owen](http://www.kytrinyx.com/). Katrina is a polyglot developer and Ruby Hero award winner who accidentally became a developer while pursuing a degree in molecular biology. She began nitpicking code back in 2006 while volunteering at JavaRanch, and got hooked. When programming, her focus is on automation, workflow optimization, and refactoring. She cares deeply about open source and contributes to several projects outside of Exercism. In 2016, Katrina decided that for Exercism to fulfill its potential, it needed a professional product team to rethink Exercism from the ground up. She recruited [Jeremy Walker](https://ihid.co.uk) as co-founder, and working with [Nicole Chalmers](https://twitter.com/n_chalmers) and the team at [Thalamus](http://thalamus.ai), they reconceived Exercism as the fully-fledged product you see today. In addition to this [leadership team](/team), Exercism is made possible by thousands of wonderful volunteers who have crafted the various language tracks and exercises that made Exercism so popular. Learn more about our [mentors](/team/mentors), our [track maintainers](/team/maintainers) and our thousands of [contributors](/team/contributors). -### What's with the name "Exercism"? +## What's with the name "Exercism"? Despite being one vowel away from "exorcism", the name has nothing to do with demons or fixing "evil code". @@ -19,66 +19,66 @@ To learn more about what it means for the devil to be in the details, check out ## The Basics -### I'm lost. Where do I go? +## I'm lost. Where do I go? You're in luck. Here's a [step-by-step guide](https://exercism.io/getting-started) to get you started. If something is still unclear for you or not working then it might be the same for others so we'd appreciate you letting us know. Refer to [Opening an Issue](#opening-an-issue) below for instructions on how you can help us help others. -### I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do? +## I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do? This means that GitHub isn't willing to verify who you are. That can be because you chose not to give permission or it might be because your GitHub account is not properly configured. A common problem is that you haven't verified your email address on GitHub. You can check that in your [GitHub email settings](https://github.com/settings/emails). -### How do I delete my account? +## How do I delete my account? You can delete your account by following the link at the bottom of your [settings page](https://exercism.io/my/settings). If your issue is with emails and notifications you can adjust that in [your personal preferences](https://exercism.io/my/settings/preferences/edit). -### What happened to my Team from the old site? +## What happened to my Team from the old site? We now have a [dedicated Teams site](https://teams.exercism.io). ## Exercism Command-line Client -### I can't submit! What should I do? +## I can't submit! What should I do? The new site has a brand new command-line client, and also needs some extra metadata for your exercise. Read about how to [upgrade your command-line client and migrate your solutions for the new site](/cli-v1-to-v2). If that doesn't help, or you didn't use the old version of the command-line client, please read through the [command-line client Walkthrough](https://exercism.io/cli-walkthrough). If that doesn't help either, [open an issue](https://github.com/exercism/CLI/issues/new) and we will help you get it sorted out. -### How do I check the version of my command-line client? +## How do I check the version of my command-line client? The version command `exercism version` outputs the running version of the Exercism command-line client. By running the version command with the latest flag `exercism version --latest` you can check if there is a newer version available. -### How do I upgrade to the latest version of the command-line client? +## How do I upgrade to the latest version of the command-line client? The command `exercism upgrade` will upgrade to the latest available version of the command-line client if one is available. -### I get permission denied errors when upgrading! What should I do? +## I get permission denied errors when upgrading! What should I do? If you are receiving permission denied errors when trying to upgrade the command-line client, chances are the binary was installed via a system package manager (e.g Homebrew) or has been installed into a directory that you no longer have write access to. If your command-line client was installed via a package manager please use your package manager for upgrading, as opposed to running the `exercism upgrade` command. If your command-line client was installed manually, please check the path of the Exercism command-line client `which exercism` on Linux and MacOs, `where exercism` on Windows and ensure that the returned path is a directory you created. If so, use the tools provided by your system to change the permissions of the directory to grant write access to your user and trying upgrading again. If you are not sure if you created the directory, or the returned path is a system path, please use your system tools to uninstall the command-line client and reinstall using the [interactive walkthrough](https://exercism.io/cli-walkthrough). -### I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do? +## I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do? Prior to version 3.0.5 of the Exercism command-line client, there was a bug in the upgrade command that would replace the command-line client binary file with a single text file causing the "16-bit MS-DOS Subsystem" error. To resolve this issue remove the corrupt binary and reinstall the command-line client using the [interactive walkthrough](https://exercism.io/cli-walkthrough). ## Mentored Mode -### My queue hasn't updated in a while - is there something wrong? +## My queue hasn't updated in a while - is there something wrong? While wait times can be longer than normal for a number of reasons (number of mentors, time of year), it can also appear that the queue is not updating. This is not unusual and you should see movement fairly soon. If you your wait is far longer than the average, refer to [Opening an Issue](#opening-an-issue) below. -### How many mentors does my track have? I only see a handful on the website. +## How many mentors does my track have? I only see a handful on the website. The website only shows mentors who have provided bio information for the website, not the actual number of mentors who are actively reviewing solutions. Rest assured, there are mentors working through their queues so hang in there! -### I submitted the wrong solution / file. What can I do? +## I submitted the wrong solution / file. What can I do? There isn't a way to delete submissions so just submit the right file and it will show up as a new iteration in the queue. Feel free to leave a note for your mentor with the original submission clarifying what happened. -### How can I report abuse or examples of bad mentoring? +## How can I report abuse or examples of bad mentoring? Please check our [Code of Conduct](https://exercism.io/code-of-conduct) for more information about our expectations of conduct. If you would like to report something, please reach out to us at [abuse@exercism.io](mailto:abuse@exercism.io?subject=%5BCoC%5D]) and we will try to fix or resolve the issue respecting both you and your privacy. ## Improving Exercism -### This is great! How do I get involved? +## This is great! How do I get involved? There are a few different ways - becoming a mentor, managing a language track or reporting (or addressing!) issues on GitHub. You can see more on the [How to Contribute page](https://exercism.io/contribute). Version 3 of Exercism is also being built right now and needs lots of help. The [v3 repository](https://github.com/exercism/v3) has more information. -### How do new language tracks get added to the site? +## How do new language tracks get added to the site? A new language track gets created when a member of the community takes the lead on it and becomes a maintainer of the track. If you'd like to get involved in helping set one up, there are [instructions here](https://github.com/exercism/request-new-language-track/blob/master/README.md). -### Why are issues taking a while to get resolved? +## Why are issues taking a while to get resolved? Version 3 of Exercism is being actively worked on, which means that contributors and maintainers are splitting their time between the current version (V2) and the next. ## Opening an Issue @@ -91,7 +91,7 @@ Before submitting an issue, be sure to check the relevant GitHub issue tracker t You can search through issues (remove the `is:open` filter to include closed/resolved issues). Try a few different keywords. -### What if my issue is not listed here or in GitHub? +## What if my issue is not listed here or in GitHub? If your problem hasn't been resolved or reported, then create an issue in the appropriate repository by selecting the green **New issue** button. Make sure to include the following information: @@ -100,7 +100,7 @@ Make sure to include the following information: 1. Instructions on how to reproduce the issue 1. If applicable, reference to any related issue using its issue number (formatted like #1203) -### What if there is an issue with language on the website? +## What if there is an issue with language on the website? If your issue pertains to an exercise in your language track, then please find the correct language track [from this list](https://github.com/search?q=topic%3Aexercism-track+org%3Aexercism+fork%3Atrue) and submit an issue there. Please specify if the issue is with the instructions or something language specific, using the template below. If you have spotted a typo or if you have a suggestion for clearer language or instructions on the general website, then [create an issue for Exercism Website Copy](https://github.com/exercism/website-copy/issues/new) with the following information: diff --git a/pages/getting_started.md b/pages/getting_started.md index 654bf3e9e..b28e8d1c0 100644 --- a/pages/getting_started.md +++ b/pages/getting_started.md @@ -1,35 +1,37 @@ -### Help! What do I do? +# Getting Started + +## Help! What do I do? We know using a new product can be daunting, and Exercism is a little complicated. So here's a really simple set of instructions to get you started. -#### Sign up +### Sign up 1. Sign up at exercism.io using either your GitHub account, or by using your email address and choose a password. 2. If you sign up using an email address, you now need to confirm it. Look for the email, click the link, then log in. -##### Language and exercises +#### Language and exercises 3. You will now see a list of all the [language tracks](/tracks) you can join. You can click through as many as you want to explore. 4. Once you've found a language you want to join, click the "Join Track" button. 5. You will now be taken into your new track. You'll see a core set of exercises at the top and some side-exercises below. 6. Start with the first **core** exercise on the track, which is normally called "Hello World". Click on the exercise to begin. 7. You will see some information and some instructions on the left-hand side and a button on the right-hand side labelled "Begin Walkthrough". Click on this and follow the instructions. -##### Submit your solution, mentoring +#### Submit your solution, mentoring 8. You should now have the CLI installed and the exercise downloaded to your computer. Solve the exercise and then upload it using `exercism submit /PATH/TO/SOLUTION` 9. In your web-browser, go back to the [language tracks](/tracks) page, choose your exercise and the exercise you've just worked on. You will now see your solution online and notice that it is awaiting a mentor. 10. A mentor will now come and give you feedback on your solution. This can happen really quickly (15 minutes) or take a little while (a day or two) depending on demand. In the meantime, you will find other exercises on your track are available for you to solve! -##### Iterations, resubmit +#### Iterations, resubmit 11. Once you've received feedback, you can make some changes to your solution and then resubmit it (see step 8). This may happen a couple of times before the solution is approved. 12. Once the solution is approved by a mentor, you click 'complete' to mark the solution completed. This will unlock lots more exercises. -##### Get involved: mentoring or maintaining a track +#### Get involved: mentoring or maintaining a track 13. You're now an Exercism pro! :) 14. Fancy giving back to Exercism and helping others? We always need more [mentors](http://mentoring.exercism.io) and [track maintainers](/become-a-maintainer) and we'd love you to get involved! -### Just want to download the new CLI? +## Just want to download the new CLI? You can always get the [latest release on GitHub](http://github.com/exercism/cli/releases/latest). -### Still stuck? +## Still stuck? Check out our [FAQs](/faqs) or [contact us](/contact). diff --git a/pages/how_do_mentor_queues_work.md b/pages/how_do_mentor_queues_work.md index e9bc0b699..692eeb1f2 100644 --- a/pages/how_do_mentor_queues_work.md +++ b/pages/how_do_mentor_queues_work.md @@ -1,3 +1,5 @@ +# How mentor queues work + Mentors are free to choose whichever submissions they want to mentor. Normally, though, they work through either a track's queue (e.g. all the Ruby submissions), or an exercise's queue (e.g. all the Ruby High-Scores submissions). diff --git a/pages/mentored_mode_vs_independent_mode.md b/pages/mentored_mode_vs_independent_mode.md index 16bdf1732..924736b13 100644 --- a/pages/mentored_mode_vs_independent_mode.md +++ b/pages/mentored_mode_vs_independent_mode.md @@ -1,8 +1,10 @@ -### Introduction +# Mentored Mode vs Independent Mode + +## Introduction Tracks can be completed in two modes on Exercism - Mentored Mode and Practice Mode. You can choose a different mode for each track. -### Mentored Mode +## Mentored Mode Mentored Mode gives you the full Exercism experience. The track progresses in a structured manner, teaching you a new skill with each exercise. Every time you submit a solution, a mentor will give you feedback and advice on how to improve your code. Once you've made a little progress, they'll approve your solution and you can unlock the next step in the track. @@ -10,14 +12,14 @@ Every time you complete a solution, you'll also unlock extra bonus exercises. Th We try to respond to all core submissions within 24hrs, but as our mentors are volunteers helping in their evenings and weekends, we can't guarantee that we will hit that goal. Our bonus exercises hopefully mean you won't get frustrated waiting for feedback :) -### Practice Mode +## Practice Mode We designed Practice Mode for people who want to take fast, deep-dives into a language without waiting for mentor feedback. In Practice Mode you can take the exercises in whatever order you want and there is no progression or unlocking. You may request mentoring on one exercise at a time, but your solutions will have a lower priority than people in Mentored Mode. -### Changing mode on a track +## Changing mode on a track While we recommend sticking to one mode per track, it is possible to change if you decide you've made the wrong decision. You will find the button in the "Danger Zone" section of a track page, which is on the right-hand-side in Mentored Mode and the bottom of the page in Practice Mode. -### Oversubscribed tracks +## Oversubscribed tracks Some tracks are oversubscribed, meaning there are too many students per mentor. In this situation, anyone starting the track is forced to start in Practice Mode, and no-one in Practice Mode will be able to request mentor help until the track is back in a "healthy" state. At the time of writing, we define an oversubscribed track as one that has a median wait time of over one week. diff --git a/pages/mentoring_faqs.md b/pages/mentoring_faqs.md index 246f94c66..1c696ca95 100644 --- a/pages/mentoring_faqs.md +++ b/pages/mentoring_faqs.md @@ -1,3 +1,5 @@ +# Mentoring FAQs + Here we have collated a list of the questions asked frequently by mentors. If you have a question that hasn't been answered here, please post it on the **[\#questions](https://exercism-team.slack.com/archives/CAQP7JL3T)** channel on Slack. ## Getting Started diff --git a/pages/mentoring_getting_started.md b/pages/mentoring_getting_started.md index f713c0ce7..befc9477a 100644 --- a/pages/mentoring_getting_started.md +++ b/pages/mentoring_getting_started.md @@ -1,11 +1,13 @@ +# Mentoring Getting Started + Hi new mentor! Awesome to see you here! Most of us were a bit... shy..?... anxious...?....feeling inadequate..?... before we started mentoring, so we've written down some tips based on our own experiences to help you with your adventure in mentoring. Hope it helps! -### 1. Start with the early exercises +## 1. Start with the early exercises Your [dashboard](https://exercism.io/mentor/dashboard) lists the exercises. When you start as a mentor, we'd recommend to not follow the suggested order, but pick the starter exercises in the track, like the first core exercise (_TwoFer_ in most tracks), and the first side exercise (for Ruby: _Acronym_). You can find a list of all the side exercises on your own profile page. Or, ask your fellow mentors in the Slack track channel. -### 2. Solve the exercise yourself +## 2. Solve the exercise yourself This has multiple benefits: - You'll know what new students experience when downloading exercises with the Exercism CLI - You'll have to solve the exercise in a way that passes the tests - and nothing more. @@ -13,33 +15,33 @@ This has multiple benefits: As the queues for side exercises in the tracks are huge, time-to-mentor can be long. You can either mentor yourself by reading the [Mentor Notes](https://github.com/exercism/website-copy/tree/master/tracks) if those are available, or ask your fellow mentors in the Slack channel for their favorite solutions, or ask them to look at your solution. You may want to add that you're asking because you want to start mentoring that exercise. -### 3. Mentor that exercise first +## 3. Mentor that exercise first - In your Mentor Dashboard, filter the list of exercises for your track and the one exercise. Work through a bunch of the submissions for this exercise. It'll give you a feel for the different kinds of students that you'll meet in your track, and you'll be suprised by the wide variety of solutions that people submit. We encourage you to be picky :-) Nothing wrong with discarding the submissions you don't feel confident about. - It pays off to record all your comments from the beginning; and start collecting some links to the most frequently used resources to point to. -### 4. Your time investment +## 4. Your time investment - Mentors are asked to commit to one hour a week, and it is listed on the site that one hour equals 20 mentorings. When you start mentoring, it's impossible to meet that goal. - If you're willing and able to give it more than one hour weekly in the beginning, it will bring you up to mentoring speed faster, but please don't measure your success against the numbers. - If you're bound to one hour, start with only one student's submission, and follow that through until approval. - When you build your mentoring experience, know the exercises better and have a collection of notes you can rely on, you'll be much faster. Even then, every once and a while a review can take longer. -### 5. Mentor Notes in your track +## 5. Mentor Notes in your track We try to add Mentor Notes for every exercise; it's a work in progress so there may not be any for the track or the exercise you're mentoring. If there are notes, a button 'View community mentoring notes' will appear on your mentor dashboard as soon as you select a submission to mentor. Mentor Notes show one or more variants of acceptable solutions. Some also list common topics that your fellow mentors discuss in their mentoring, and/or common pitfalls. -### 6. Mentoring Tips: general +## 6. Mentoring Tips: general - Please do not approve a solution without any comment. Especially new programmers may have spent lots of time to get the tests pass. At least acknowledge that they managed to pass the tests. - Prefer telling the student what you like about a solution rather than pass a judgement - even if it's a positive judgment. - Be aware that your student may not be a native English speaker. If they seem to misunderstand your comments, try a different wording. -### 7. Mentoring Tips: early exercises +## 7. Mentoring Tips: early exercises - When the logic in the solution does not meet the standards, give them one step to work on. It pays off to start with the most important thing. In these early exercises, try not to explain the Why's of the language. Link to tutorials or blogs aimed at beginners in the language that shows _how_ things are done. Even when it's showing the solution to the exercise ad verbatim. - When it's only syntax things, you may approve the solution and list the issues. You may want to link to a style guide if that's available in your language. As opinions on style tend to differ a bit ;-), make it a suggestion, not a rule. (For instance: "Unless you have strong opinions on style, I'd recommend following the Style Guide.") We don't enforce a particular style guide; being consistent is the main concern here. - In the next iteration, follow the pace of the student. When they changed only one thing, and didn't take into account the effect of that one change on the rest of the code, just give them one step more. When the one step lead to more in-depth changes, take it from there. -### 8. Mentoring tips: more advanced exercises +## 8. Mentoring tips: more advanced exercises - When you're advancing to more advanced exercises, it's still worthwhile to work on a few submissions of the same exercise. When you've seen enough to understand the problems students run into, it gets easier (and faster) - The goal is for students to learn and to become more fluent in the language, not per se to deliver the optimal solution. When a student's first submission is already correct and idiomatic, we'd like to challenge them to take it one level up. When a student's first submission is not meeting the standards of the language or the logic, the mentoring aims at getting them to a 'minimal viable solution'. That may take one or more iterations, and mentoring can stop when that goal is reached. - Chances are you love your programming language as much as we love ours. It may be tempting to dive deep into the language's internals, and it's one of the aspects that adds to the mentoring fun. However, mentoring this way can also become a time consuming hobby. The choice is yours; we just don't want the mentoring to get overwhelming, so please know that mentoring doesn't _need_ to go that far. diff --git a/pages/mentoring_guide.md b/pages/mentoring_guide.md index 36b703a7b..a9684e84c 100644 --- a/pages/mentoring_guide.md +++ b/pages/mentoring_guide.md @@ -1,8 +1,10 @@ -### Getting Started +# Mentoring Guide + +## Getting Started Thanks for being here! There are two stages to getting started. The first is to get involved in the community and the second is to try mentoring. -#### Joining the community +### Joining the community 1) We have a private Slack room for mentors. You should have received an invite when you signed up. If you didn't, email us at [mentoring@exercism.io](mailto:mentoring@exercism.io). 2) In Slack, introduce yourself in the #introductions channel. @@ -11,7 +13,7 @@ Thanks for being here! There are two stages to getting started. The first is to 5) [Submit your bio](https://github.com/exercism/website-copy/blob/master/mentors/README.md#mentors) to appear as a mentor on the Exercism website. 6) (Optional: Post a testimonial on #testimonials if you've had previous good experiences of Exercism and want to give everyone some encouragement) -#### Starting mentoring +### Starting mentoring Now you're set up in the community, you'll want to start mentoring. @@ -19,6 +21,6 @@ Now you're set up in the community, you'll want to start mentoring. - Next, have a quick read of our [Getting started with mentoring guide](https://exercism.io/mentoring-getting-started). Depending on how confident you feel you might want to skim it over and just get stuck in, or have a thorough read to get a really solid understanding how the process works. - Our [Mentoring workflow guide](https://exercism.io/mentoring-workflow) will give you a quick walk through of how the mentoring section of Exercism works and show you the normal workflow. -### Resources +## Resources - We have mentor notes for many of the exercises. You can currently find them [on GitHub](https://github.com/exercism/website-copy/tree/master/tracks). - If you have any questions, check out our [Mentoring FAQs](https://exercism.io/mentoring-faqs) or post in [#questions on Slack](https://exercism-team.slack.com/messages/CAQP7JL3T). diff --git a/pages/mentoring_workflow.md b/pages/mentoring_workflow.md index 676001e3e..487cb24b5 100644 --- a/pages/mentoring_workflow.md +++ b/pages/mentoring_workflow.md @@ -1,4 +1,6 @@ -### Navigating the Mentor Dashboard +# Mentoring Workflow + +## Navigating the Mentor Dashboard To get started with mentoring, log into your Exercism account and click on “Mentor Dashboard” in the main menu. ![menu](https://user-images.githubusercontent.com/5421823/42646491-efd24170-85f8-11e8-9284-87929f379f39.png) @@ -11,7 +13,7 @@ The right hand side shows how many solutions you’ve mentored so far so you can Click on one of the solutions to start giving feedback. This will take you to the mentor feedback interface where you can write and submit your feedback. -### Giving Mentor Feedback +## Giving Mentor Feedback You can click the “Instructions” tab to remind yourself of what the exercise is about. These are the same instructions given to the learner. diff --git a/pages/privacy.md b/pages/privacy.md index 7276d398f..6217e5d23 100644 --- a/pages/privacy.md +++ b/pages/privacy.md @@ -1,3 +1,4 @@ +# Privacy Policy Last Revised: April 2019 diff --git a/pages/report_abuse.md b/pages/report_abuse.md index 22999bd84..ae758f81b 100644 --- a/pages/report_abuse.md +++ b/pages/report_abuse.md @@ -1,3 +1,5 @@ +# Report Abuse + Feeling uncomfortable? Had a worrying or uncomfortable interaction with someone on the site? Has something written on Exercism concerned or upset you? Please reach out to us and we will try to fix or resolve the issue respecting both you and your privacy. The best way to contact us is to email us at [abuse@exercism.io](mailto:abuse@exercism.io). diff --git a/pages/roadmap.md b/pages/roadmap.md index fcbe1ffa2..c7cac1c44 100644 --- a/pages/roadmap.md +++ b/pages/roadmap.md @@ -1,23 +1,25 @@ +# Roadmap + _This page deals with the various individual tasks that the team are focused on. Before reading this, you may be interested in reading about [Exercism's Strategy](/strategy) to place the items below in context._ This is a rough roadmap for Exercism. It is split into our short term goals (<12 months) and our longer-term goals, which will be dependant on the success of our short-term objectives. Each section is split roughly in priority order, and sections are ordered as per our general priorities. ## Short-term goals -### Bugs +## Bugs - There are lots of little issues that need resolving from the launch of v2. Anything tagged with `type/bug` on the exercism/exercism repo needs sorting. You can explore that list [here](https://github.com/exercism/exercism/issues?q=is%3Aissue+is%3Aopen+label%3Atype%2Fbug). - **Fix issues with exercises not being unlocked:** [#3867](https://github.com/exercism/exercism/issues/3867). -### Abuse and quality control +## Abuse and quality control - **Add a button for mentors to report learners** [#4306](https://github.com/exercism/exercism/issues/4306). -### Curriculum +## Curriculum We are actively working to explore what an exemplar syllabus would look like for the Ruby track, considering things such as learning pathways, goals, mentoring-burden. We will then explore where the gaps are and what new exercises might be created as part of this. Once we have made some basic progress we will widen the discussion to include a small set of sample tracks with active maintainers. -### Mentoring Tools +## Mentoring Tools - Adding personalised mentor notes per exercise, viewable and editable within the UI. [#4083](https://github.com/exercism/exercism/issues/4083) - Adding 'Comment and Request changes' to mentoring UI, which will prompt the learner to submit another iteration (a little like Code Review on GitHub) @@ -29,50 +31,50 @@ We are actively working to explore what an exemplar syllabus would look like for - Calculate mentors' "weekly progress" per track [#4438](https://github.com/exercism/exercism/issues/4438) - **Send content with mentor emails:** [4428](https://github.com/exercism/exercism/issues/4428) -### Usability and documentation +## Usability and documentation - **Make the steps of the installation guide linkable:** [#4470](https://github.com/exercism/exercism/issues/4470) - **Add more information about timescales for mentoring:** [#4368](https://github.com/exercism/exercism/issues/4368). - **Download link on all iterations** Add the download link and a link to instructions on all iterations in the student's view. [#4259](https://github.com/exercism/exercism/issues/4259) -### Profiles and public solutions +## Profiles and public solutions - **Allow users to change which iteration is published:** At the moment only the most recent submission is published. We will allow users to choose any of the iterations to make public. - **Allow deletion of iterations:** Often people submit iterations by default. This will allow people to delete them. [#3848](https://github.com/exercism/exercism/issues/3848) - **Add display name option:** [4365](https://github.com/exercism/exercism/issues/4365) - **Enable commenting on community solutions:** We are going to let people decide whether want comments enable on a per solution basis. -### Maintainer Tools +## Maintainer Tools We want to update the new website to allow for an easy and pleasant experience for track maintainers and will build out tools within the UI to allow them to more easily experiment with track setups. -### Accessibility +## Accessibility There are various [a11y](https://a11yproject.com/) improvements we are making, spearheaded by [@unused's plan here](https://github.com/exercism/website/pull/182). -### Changelog +## Changelog We want to add a changelog into the site that all maintainers and contributors can add to. Rather than being a static page, this will be a functional product. We envisage that a maintainer would submit an entry saying "We've added a new exercise called XYZ to the ABC track". This would then appear on the changelog with a nice track icon, and the Track's twitter account (yes, every track will have its own account) will then tweet that out. The changelog will be filterable by track or topic and have built in searching. -### Public API +## Public API We want to define a public API that will allow others to integrate Exercism into their code editors [#4087](https://github.com/exercism/exercism/issues/4087). -### Automated running of the tests +## Automated running of the tests We want to create true integration tests that run against production that test sign up, track creation, mentoring and then delete the user. These will run after each deploy of both new code and changes to a track to ensure nothing has broken. We see this as a long-term goal and not something that will be implemented in the next 6 months. -### Automated code analysis of submissions +## Automated code analysis of submissions We used to have a bot called Rikki that used the [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) to work out what anti-patterns were being used and provide an automatic comment. We want to evolve this to provide a suggested comment to mentors that they can give to students (we may sometimes choose to make it automatic - we need to explore this further). We imagine using a mixture of Machine Learning and AST analysis to do this and will probably prototype it on 1-3 tracks first. ## Long-term goals -### Online completion of exercises +## Online completion of exercises Remove the requirement to install the CLI allow people to complete the exercises and run the tests on the Exercism website. This will also allow us to automatically run tests against submitted code to test that it works and help mentors. -### Multilingual support +## Multilingual support We really want to support multiple languages, but doing this is a huge, complex project, which would involve translating the exercises, website, etc., as well as being able to recruit mentors into a specific language. We're currently exploring what a first stage of this might look like for PT-BR [here](https://github.com/exercism/exercism/issues/4207). diff --git a/pages/strategy.md b/pages/strategy.md index e01cf27cf..68a652e4d 100644 --- a/pages/strategy.md +++ b/pages/strategy.md @@ -1,3 +1,5 @@ +# Strategy + ## Introduction Exercism is a large complex project with thousands of contributors working across dozens of projects, all trying to achieve ambitious goals. It would quickly become overwhelming if we were all working towards making Exercism perfect, so to keep things manageable, we periodically determine the critical next step for Exercism to achieve its goals and then plan that into a strategy. We present this using the OST framework - defining an **Objective**, which will aim to achieve with a **Strategy**, implemented by a series of **Tactics**. diff --git a/pages/terms_of_service.md b/pages/terms_of_service.md index bb1a6da39..bf94c4e9a 100644 --- a/pages/terms_of_service.md +++ b/pages/terms_of_service.md @@ -1,3 +1,5 @@ +# Terms of Service + Last Revised: April 2019 ## Overview diff --git a/pages/values.md b/pages/values.md index 09541edfd..8ec266377 100644 --- a/pages/values.md +++ b/pages/values.md @@ -1,15 +1,17 @@ -### Preamble +# Exercism's Values + +## Preamble Exercism first began to **give people opportunity**. Katrina wanted Exercism to offer people who didn’t necessarily have opportunities handed to them the chance to attain a better standard of living and a better life. **Learning programming is hard and overwhelming** and there are a bajillion resources, but most of them are too difficult, confusing, condescending, boring, vast or patchy. By creating **lovingly-crafted resources** with a **positive and caring community**, Exercism has helped **empower thousands of people** to realise that programming has the potential to be **fun, exciting, and interesting**, and give them the confident realisation that they can **succeed and thrive**. -### Mission Statement +## Mission Statement To enable anyone to achieve [fluency](#fluency) in any programming language for free, in order to give opportunity to all and improve the quality of software development worldwide. -### Values +## Values We envision a world where anyone from any background can become fluent in any programming language for free. Through programming exercises, resources and a safe and nurturing community, we help people develop their fluency in programming languages, enabling them to build understanding and confidence, which empowers them to take the next steps in their careers as software developers. -### Core Principles +## Core Principles Based on this, we consider this is what Exercism looks like at its core: - Exercism’s value is in the community, the discussion and the learning. - Exercism should be enjoyable, challenging and valuable. @@ -18,7 +20,7 @@ Based on this, we consider this is what Exercism looks like at its core: - Exercism should not be limited to being an online tool. It could be used in schools or in places without good internet access. -### Fluency +## Fluency Exercism is about improving Fluency, defined as “the ability to express oneself easily and articulately in a particular language”. In programming terms, becoming fluent in a language is critical because it frees up cognitive resources for the more advanced parts of software development. Mastering the basic syntax, idioms, conventions, and standard library of a programming language allows for the brain to focus on actual problem-solving. Once you have achieved fluency at the basic level, it is much easier to improve your proficiency, and then ratchet up your fluency as you go.