Improving instructions from dnd character exercise

[manumafe98]

pull request

the issue addresses: #2334

The goal is to improve the documentation on dnd character exercise.

Reviewer Resources:

Track Policies

[manumafe98]

I guess that for this pr to be applied I should also modify this

[sanderploegsma]

The documentation for practice exercises is generally generated from the problem specifications - in fact from the document you linked to above. This means that any changes made to a practice exercise's .docs/instructions.md in this repository will get overwritten the next time we sync it with the problem specifications. You can try that out on your own branch by using the Configlet:

$ bin/fetch-configlet 
Fetching configlet...
Downloaded configlet 4.0.0-beta.16 to ./bin/configlet

$ bin/configlet sync --docs --exercise dnd-character --update
Updating cached 'problem-specifications' data...
Checking exercises...
[warn] docs: instructions unsynced: dnd-character
sync the above docs ([y]es/[n]o)? y
Updated the docs for 1 Practice Exercise
The `dnd-character` exercise has up-to-date docs!

Since the problem specifications are used by all Exercism tracks, the instructions there are written so that they can apply to each track. This means that they explicitly do not contain any implementation details for an exercise, just a description of the problem to solve.

Any track-specific information that we as maintainers think are valid to append to the instructions can be placed in the exercise's .docs/instructions.append.md. This file is not synced with the problem specifications and can therefore be edited.

Finally, exercises can optionally also contain a .docs/introduction.md file, which is shown before the instructions. It is common for concept exercises to have both, but for practice exercises this rarely happens.

[sanderploegsma]

With the above in mind, I would propose the following:

1. The .docs/instructions.md should never deviate from the problem specifications, so please roll back any changes to it
2. Add additional instructions that are relevant for the Java track in the .docs/instructions.append.md.
3. Don't add .docs/introduction.md as there is no introduction needed before the instructions from the problem specifications.

[manumafe98]

Thanks for the review Sander, I made the changes you asked.
For me the only thing that needs clarification in this exercise is the fact that the character should be Unique or do you think we could add something else to help the user?

[sanderploegsma]

Just FYI: I haven't forgotten about this PR, I just haven't had time to write down my thoughts on it. I'll try to have it reviewed some time this week!

[manumafe98]

No problem! and thanks for letting me know!

[sanderploegsma]

What do you mean by this? I'm not familiar with any unique concept in Java.

[manumafe98]

I was trying to refer to this test

java/exercises/practice/dnd-character/src/test/java/DnDCharacterTest.java

Line 187 in cce8452

public void testUniqueCharacterIsCreated() {

[sanderploegsma]

If I look at the original issue I'm not sure that these additions really improve the instructions. I see two ways of going forward:

1. We update the instructions.append.md where we basically spell out what is required from the student (which is what the original issue asks for).
2. We don't update anything. "I had to decipher the tests to understand what my solution should do" is feedback that is frequently given on the forum and on Discord, and the usual response is "that's right, because practice exercises on Exercism take a Test Driven Development approach".

I personally favor the second option.

[manumafe98]

If I look at the original issue I'm not sure that these additions really improve the instructions. I see two ways of going forward:

1. We update the instructions.append.md where we basically spell out what is required from the student (which is what the original issue asks for).
2. We don't update anything. "I had to decipher the tests to understand what my solution should do" is feedback that is frequently given on the forum and on Discord, and the usual response is "that's right, because practice exercises on Exercism take a Test Driven Development approach".

I personally favor the second option.

Yeah you're right, the changes are minimum and the second options tends to be the way of solve exercises in exercism, so what do we do with the issue? we close it?

[sanderploegsma]

Yes I think we should explain our perspective and close it.