Concept exercise files

I forgot to add the .meta/design.md to a recent PR. The documentation says that this file is required for concept exercises (to prevent future feature creep), but configlet lint didn’t flag it as a problem.

I’m sure this is nobody’s most urgent priority, but would it be worth adding this check in a future release of configlet? Or is the file only sort-of-required?

1 Like

IIRC, it is only sorta required (not every concept exercise on every track has them). That being said, they are really important for clarifying what is in and not in a given concept/concept exercise.

I’m for adding in a check in configlet when there’s time/energy. :slightly_smiling_face:

2 Likes

Fortunately, no rush - it could take a while to get to this state!

Incidentally, I realized since my original post that configlet create --concept-exercise does not create this file, nor .docs/hints.md.

I know a few people are working on a learning syllabus at the moment, so we all need to remember to add these manually if we think they’re a good idea. At least this only affects maintainers, not the vast majority of students.

2 Likes

I think the hints.md file was considered not required originally for concept exercises. The theory being that a concept exercise is very constrained, and should have everything a student needs to solve the problem written out in either the introduction.md or instructions.md file.

In practice, hints.md is useful for students working on an exercise, irrespective of it being a concept or practice one.

My personal rule is to try and add a hints.md file for any “complicated” exercise - practice or concept - and for any concept exercise that’s had repeated asks for help or clarification.

2 Likes

When I PR’d a concept exercise a few weeks ago, @BNAndras leaned on me pretty firmly to fill in the hints file. I guess experienced mentors understand the value of it.

2 Likes

I also think that the hints file is a pretty useful resource for students. At the very least I reiterate the things from the introduction.md, as some might have missed it.

Please create an issue in the configlet repo for this! I agree that the design.md document should be included.

1 Like