Update Diamond

[iHiD]

Changes:

1. Tweak initial wording
2. Start with examples - it makes it much clearer
3. Remove middots to represent spaces and just use spaces.

I'd ideally like to get this merged ASAP as it's the featured exercise this week, but I'm very open to improvements/corrections! :)

[ErikSchierboom]

Approving with one suggestion

[Cool-Katt]

Sounds to me a bit more clear this way. ¯_(ツ)_/¯

[tasxatzial]

3. Remove middots to represent spaces and just use spaces.

Is there any specific reason behind this change? With dots, it's easy to see the spacing between letters. Not so much with spaces.

[tasxatzial]

Also, this might be a good opportunity for a small story?

---

In a quiet corner of the ancient Library of Patterns, you discover the Codex Diamantum, an artifact whispered about in legends. As you open it, the first page reveals a trial known to test skill, focus, and creativity: creating a perfect diamond shape from letters.

Each layer must grow outward to the middle, then shrink back in, forming a balanced and flawless pattern. The letters must align perfectly, their symmetry reflecting precision and care. Many have tried and failed, but those who succeed are said to uncover the codex's deeper mysteries.

The air around you feels alive with anticipation. This is no ordinary task — this is your chance to prove yourself worthy of the codex's secrets. Will you rise to the challenge and craft a diamond that stands as a testament to your mastery?

---

Edit: Codex Diamantum is in italics

https://forum.exercism.org/t/a-story-for-the-diamond-exercise/14036

[iHiD]

Is there any specific reason behind this change? With dots, it's easy to see the spacing between letters. Not so much with spaces.

Yes. I thought you had to use dots to solve it when I looked at the images. As this is monospace, I think the spaces are clear enough to show what's happening.

[iHiD]

Also, this might be a good opportunity for a small story?
Yes, I'd love that. But as a follow up PR please! :)

[tasxatzial]

Yes. I thought you had to use dots to solve it when I looked at the images

This could have easily been solved with an explanation:

In the following examples, spaces are shown using · characters for clarity, but in the final shape, they are actual spaces.

[iHiD]

This could have easily been solved with an explanation:

That was already there. And I missed it.

I think the exercise is pretty obvious from the diagrams, without really needing to read through all the bullet points. So making someone read them (and other details like spaces -> dots) to clarify the diagram (because the diagrams aren't actually representative of the output) feels like we're asking people to do unnecessarily work to me.

[Cool-Katt]

I think the exercise is pretty obvious from the diagrams, without really needing to read through all the bullet points. So making someone read them (and other details like spaces -> dots) to clarify the diagram (because the diagrams aren't actually representative of the output) feels like we're asking people to do unnecessarily work to me.

I second this, I have to admit I only glanced at the bullet points so I could have easily missed this.

[tasxatzial]

That was already there. And I missed it.

I'm genuinely confused. The examples are only meant to illustrate the shape of the diamond. Isn't the first thing anyone will do to look at the tests in order to see the actual requirements? Won't they immediately notice that there are no dots?

I think the exercise is pretty obvious from the diagrams, without really needing to read through all the bullet points.

The bullet points are another part of the exercise that, to me, seem to try too hard to explain the requirements. Personally, I'm not sure how I feel about reading 12 lines of instructions.

[Cool-Katt]

Isn't the first thing anyone will do to look at the tests in order to see the actual requirements? Won't they immediately notice that there are no dots?

You'd be surprised at the amount of people that wouldn't ever consider reading the tests...

[tasxatzial]

The letters form a diamond shape, and the diamond has a square shape? This is unclear. The square shape refers to what?

[tasxatzial]

I see where my confusion came from. The diamond is introduced before explaining what it refers to. Might be better to simply reverse the order of the first two requirements

Edit: Removing the unneeded repetition of the word 'shape' may also be preferable since the requirements seem to suggest that we have both a diamond shape and a square shape

Suggested change

	- The diamond has a square shape (width equals height).
	- The letters form a diamond shape.
	- The letters form a diamond shape.
	- The width of the diamond is equal to its height.

[tasxatzial]

Despite the ongoing discussion and suggestions, I've decided that this is good enough for approval. Given the nature of the problem, I believe there will always be some ambiguity in how the verbal instructions are interpreted, so I'm not going to stress too much about the choice of words. The instructions are mostly fine as they are, but due to the challenge of articulating the exercise in words, I don't believe people will find them particularly helpful. I expect most people will simply refer to the visual diagram. Moreover, it's impossible to solve the exercise without looking at the tests. Therefore, as long as there are no contradictions in the current instructions, I'm okay with it.

Approved with suggestion (see prev review)

[Cool-Katt]

I suppose it's better to agree that it's fine as it is, and argue about wording later on the forum.

[tasxatzial]

@Cool-Katt It might be better to wait until Jeremy comes along. Perhaps the wording is something that does concern him.

[Cool-Katt]

@tasxatzial
I'm definitely not yoloing with a merge, I just want to make the damn CI pass but apparently it's not happening.

[glennj]

The markdown linter doesn't like the trailing spaces in description.md

https://github.com/exercism/problem-specifications/actions/runs/12168211336/job/33938555168#step:6:196

[tasxatzial]

I just want to make the damn CI pass but apparently it's not happening.

Yeah, I was referring to that. Jeremy might come along and wipe everything out, depending on how he decides to handle this. I've come across exercises that directly point to the test suite from the description instead of trying to explain the requirements. I believe the same approach could work here. Even if the requirements are completely removed, I doubt most people would have any trouble with implementation. Based on the source link in the metadata, this seems to be treated as a TDD exercise.

Edit: Then again, if the requirements are removed, i believe this could create conflict with the intro comment in the canonical data, but i'm not sure.