Over the next few months @kytrinyx and I are going to be going through all the exercises in problem specs with the aim of making them more consistent and “human”. Raising the standard of instructions in our exercises is one of the biggest impact things we can do across the board for Exercism, and the time feels right for us to go through and do this now.
Specifically we’ll be:
Splitting description.md into introduction.md and instructions.md.
Ensuring there is something interesting or story-based in the introduction.md.
Ensuring that all the information required to solve an exercise are in the instructions.md
Ensuring that the instructions are clear and do not rely on prerequisite understanding of the exercises’ topics (e.g. maths, biology or music).
Where some subject-matter knowledge is required, ensuring it’s either explicitly explained, or that we link out to easily-consumable resources.
Ensuring the language is consistent, friendly and diverse (e.g. not just using english names in examples)
Trying to ensure that the instructions are extensible for languages that might need to add their own constraints via an append file, and that they do not create issues for languages that might have more complex implementation details.
For a sense of the specifics of what we’re doing, take a look at our first PRs to TwoFer, Bob, and Gigasecond.
We may also discover some exercises we feel should be deprecated. In those cases, we’ll open specific topics on the forum to discuss and skip that exercise for this process until those discussions are resolved.
As we’re not making any changes to the exercises themselves (i.e. not editing the test suites), these changes should not really require input from the maintainers or any technical work to implement other than syncing the introduction/instructions files, so we hope this will be a pain-free process for everyone. To make this manageable and efficient for us, we’re going to take a relatively “optimistic merging” approach to this where Katrina and I pair on each exercise and then push a finished version to problem-specifications. We’ll give a short window for anyone to raise any general concerns (or fix spelling mistakes that we’ve missed!), and then aim to merge 72hrs hours after opening. We will then PR the updated descriptions/instructions/introductions to all tracks, and merge those ~7 days later.
We’re excited to improve the consistency across our exercises and start imparting a stronger Exercism-style across our educational content!
Will the contents of introduction.md and instructions.md always be presented together, or is there any situation where one will be preferred over the other?
Yes, I think the UI should just get merged inline effectively (ie I don’t even think there should be “Introduction/instructions” headers). The main reason for the split is to allow tracks to have individual appends at those two junctures. So if you need to add something (e.g. an extra test case) you can append to both the story and the tangible instructions.
I can’t see a scenario where we choose to not have both files.
It should all work without any amendments. The API call should do the work.
The (technical, not exercise) changes were actually made during the v3 upgrade so everything should just work. But we’ll need to give it a good look over. Please let us know if you find anything that doesn’t.
@ErikSchierboom Can you try manually updating an F# one and checking the CLI locally before we merge the PS PRs pls?
# Two Fer
Welcome to Two Fer on Exercism's F# Track.
If you need help running the tests or submitting your code, check out `HELP.md`.
## Introduction
In some English accents, when you say "two for" quickly, it sounds like "two fer".
Two-for-one is a way of saying that if you buy one, you also get one for free.
So the phrase "two-fer" often implies a two-for-one offer.
Imagine a bakery that has a holiday offer where you can buy two cookies for the price of one ("two-fer one!").
You've gone for the offer and (very generously) decided to share the extra cookie with a friend.
## Instructions
Your task is to determine what you will say to your friend as you hand them their cookie.
If your friend is named Do-yun, then you will say:
```text
One for Do-yun, one for me.
```
On the other hand, if for some reason you can't remember your friend's name just then, you'll say _you_ instead of their name:
```text
One for you, one for me.
```
Here are some examples:
|Name |Dialogue
|:-------|:------------------
|Alice |One for Alice, one for me.
|Bohdan |One for Bohdan, one for me.
| |One for you, one for me.
|Zaphod |One for Zaphod, one for me.
## Source
### Created by
- @robkeim
### Contributed to by
- @ErikSchierboom
- @jrr
- @lestephane
- @valentin-p
- @wolf99
### Based on
https://github.com/exercism/problem-specifications/issues/757
