Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation about giving hints to specific instruction steps #433

Closed
fapdash opened this issue Feb 25, 2023 · 2 comments
Closed

Add documentation about giving hints to specific instruction steps #433

fapdash opened this issue Feb 25, 2023 · 2 comments

Comments

@fapdash
Copy link
Contributor

fapdash commented Feb 25, 2023

Apparently it's possible to give hints to a specific step in the instructions.md: https://github.com/exercism/common-lisp/blob/149c61afdf0025f63e5a5dc1157e1b7882df65ff/exercises/concept/pizza-pi/.docs/hints.md?plain=1#L23-L27

Which shows up in the online editor like this:
2023-02-25_12-38

I think that's really cool but I don't see this documented:

### File: `.docs/hints.md`
**Purpose:** Provide hints to a student to help them get themselves unstuck in an exercise.
**Presence:** Optional
- If the student gets stuck, we will allow them to click a button requesting a hint, which will show the relevant part of file.
- Hints should be bullet-pointed underneath headings.
- The hints should be enough to unblock almost any student.
- The hints should not spell out the solution, but instead point to a resource describing the solution (e.g. linking to documentation for the function to use).
- The hints may use code samples to explain concepts, but not to outline the solution. e.g. in a lists exercise they might show a snippet of how a certain list function works, but not in a way that is directly copy/pasteable into the solution.
- The hints must appear as a Markdown list under a `## General` heading.
- If there are no hints, the heading should be omitted.
Viewing hints will not be a "recommended" path and we will (softly) discourage using it unless the student can't progress without it. As such, it's worth considering that the student reading it will be a little confused/overwhelmed and maybe frustrated.
#### Example
```markdown
## General
- There are many [built-in methods][integers] to simplify working with integers.
[integers]: https://ruby-doc.org/core-2.7.0/Integer.html
```
---

Edit: I just realized that the example I gave is for a learning exercise, not a practice exercise, but since all exercises are moving to that format I assume that this will be possible for practice exercises following this format as well?

@fapdash
Copy link
Contributor Author

fapdash commented Feb 25, 2023

Will there even be a difference between Concept Exercises and Practice Exercises or can the two documentation pages be merged?

Edit: Answered my own question, no they can't be merged, eg. concept exercises don't have a difficulty.

@fapdash
Copy link
Contributor Author

fapdash commented Feb 25, 2023

Nevermind, practice exercises don't have instruction steps. Closing.

@fapdash fapdash closed this as completed Feb 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant