I want to improve the range of documentation I have for my some of my libraries. One kind of documentation I’m looking into is “Koans”. As I understand it, these consist of many small consecutive problems where the learner is required to fix a piece of broken code. Koans exist for different programming languages, and also for some frameworks. I can imagine they make for a fun way to learn a language or library ecosystem.
Therefore I’m looking into creating koans for some of my libraries. I have these requirements:
- The koans should have at least a way of ordering them linearly (ideally even hierarchically, to sort by topics)
- A failing koan should point the learner at a specific file to inspect, with a realistic error message they might encounter in real world
- Type errors and typed holes should be possible in a koan
- Test failures should be possible in a koan (It is fine that these would point to the failing test case instead of at the file where the error to fix is)
- There should be a way to run the koans, which only shows the error message of the smallest/first failing koan, and not all of them at the same time. (
-freverse-errors
goes some way, but not all the way) - Stretch goal: There should be a way to run a specific koan (ignoring all smaller ones)
- It should be possible to provide the solutions to all the koans, and they should be checked on CI. (It should be checked that the solutions actually compile and test fine.)
Is there anything that achieves this? Tooling, a template, or even an example koan structure that I could mimick? Does anyone have ideas how to do this?
I had some vague ideas what one could do, where I’d be interested about your feedback:
- Create a cabal package (or executable) for every koan, consecutively numbered
- Create a
cabal.project
including all the koans
To run the koans, either:
-
cabal test all
with-freverse-errors
, and tell people to solve the last error first -
cabal test 23-foo-koan
, and make sure that the packagen+1-foo-koan
depends onn-bar-koan
. Possibly, this dependency can be placed under a cabal flag so that one can work onn+1-foo-koan
without having to solven-bar-koan
first.
To ensure that there are solutions and they work, I thought about maybe using a separate branch, and then testing that on CI. But how do I make sure that I only need to make a particular small change to get to that solution? I know, that’s kind of a fuzzy constraint.