Skip to content

Commit

Permalink
Rewrite "How to implement a Haskell concept exercise"
Browse files Browse the repository at this point in the history
Before this commit, it appears that this document was a mixture between
a generic template and my initial writings about how we might go about
creating a framework for implementing concept exercises, i.e., not an
actual description of any agreed-upon approach to writing concept
exercises on the Haskell track.

Removes references to CIS 194.

Removes links to generic documents that don't seem useful.

Particularly: Preserve YouTube link of @iHiD talking. :)
  • Loading branch information
sshine authored and iHiD committed Feb 5, 2021
1 parent 30348bd commit 6f76414
Showing 1 changed file with 6 additions and 25 deletions.
31 changes: 6 additions & 25 deletions reference/implementing-a-concept-exercise.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,19 @@
# How to implement a Haskell concept exercise

This document describes the steps required to implement a concept exercise for the Haskell track.
This document describes the steps to implement a concept exercise for the Haskell track.

**Please please please read the docs before starting.** Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read the following documents:

- [The features of v3][docs-features-of-v3].
- [Rationale for v3][docs-rationale-for-v3].
- [What are concept exercise and how they are structured?][docs-concept-exercises]

Please also watch the following video:

- [The Anatomy of a Concept Exercise][anatomy-of-a-concept-exercise].
- [The Anatomy of a Concept Exercise][anatomy-of-a-concept-exercise] (video!)

As this document is generic, the following placeholders are used:

- `<SLUG>`: the slug of the exercise in kebab-case (e.g. `calculator-conundrum`).
- `<NAME>`: the name of the exercise in PascalCase (e.g. `CalculatorConundrum`).
- `<CONCEPT_SLUG>`: the slug of one of the exercise's concepts in kebab-case (e.g. `monad-transformers`).

Haskell covers a vast amount of concepts. Choosing a particular subset of concepts and an ideal ordering of these concepts is a contentious task, so the following approach is made: As a basis for both, the online resources for the CIS 194 course at Penn University is chosen.

Contributors (you) may freely choose a concept related to Haskell and implement an exercise that covers this. Before implementing such an exercise, make sure you have a good understanding of what the exercise should be teaching (and what not). Check if this concept is already partially or fully covered by another exercise, and arrange the concept in a hierarchical fashion that corresponds to the curriculum of CIS 194.
Haskell covers a vast amount of concepts. Choosing a particular subset of concepts and an ideal ordering of these concepts is a contentious task.

Because CIS 194 online course material is available in the [Spring 2013][spring-2013] and the [Fall 2016][fall-2016] version, and because these have different orderings, this does leave room for interpretation.

Because CIS 194 may not cover all subject that contributors wish to cover in this material, extending the concepts beyond the CIS 194 course should ideally be accompanied by some level of reasoning about the curriculum.
Contributors (you) may freely choose a concept related to Haskell and implement an exercise that covers this. Before implementing such an exercise, make sure you have a good understanding of what the exercise should be teaching (and what not). Check if this concept is already partially or fully covered by another exercise, and arrange the concept in a hierarchical fashion.

The directory structure of a single concept exercise looks like this:

Expand Down Expand Up @@ -73,17 +62,9 @@ These are files specific to the Haskell track:

## Step 2: Add documentation files

For the Markdown files in `.docs/` and `.meta/`, see the general advice on [how to implement a concept exercise][how-to-implement-a-concept-exercise].

## Inspiration

When implementing an exercise, it can be very useful to look at already implemented Haskell exercises. You can also check the exercise's [general concepts documents][reference] to see if other languages have already implemented an exercise for that concept.
See [documentation files][docs-concept-exercises-documentation-files].

[reference]: https://github.com/exercism/v3/blob/main/reference
[how-to-implement-a-concept-exercise]: https://github.com/exercism/v3/blob/main/docs/maintainers/generic-how-to-implement-a-concept-exercise.md
[docs-concept-exercises]: https://github.com/exercism/v3/blob/main/docs/concept-exercises.md
[docs-rationale-for-v3]: https://github.com/exercism/v3/blob/main/docs/rationale-for-v3.md
[docs-features-of-v3]: https://github.com/exercism/v3/blob/main/docs/features-of-v3.md
[docs-concept-exercises-documentation-files]: https://github.com/exercism/v3/blob/main/docs/concept-exercises.md#documentation-files
[anatomy-of-a-concept-exercise]: https://www.youtube.com/watch?v=gkbBqd7hPrA
[spring-2013]: https://www.seas.upenn.edu/~cis194/spring13/
[fall-2016]: https://www.seas.upenn.edu/~cis194/fall16/

0 comments on commit 6f76414

Please sign in to comment.