Exercise README templates: defaults, filenames and file locations

[kytrinyx]

As part of the user experience redesign process, we've started reconsidering certain implementation choices that were made early on (somewhat poor decisions made without the benefit of experience).

One decisions that has complicated things needlessly was to generate exercise READMEs on the fly based on a shared, generic problem description and some shared metadata. Eventually we discovered that we wanted to be able to include some custom text for all exercises in a single track (e.g. this is where to ask for help, or this is how to run the tests), as well as custom hints for an individual exercise.

This has had a few negative consequences beyond just the incredibly abstract and fragmented exercise README.

It's harder to pin down exactly which version of a README someone who is solving the exercise was working against, because it's made up of a number of different files in two different repositories, which could have been deployed at different commits.

If you go look at an exercise in the repository on GitHub, there's no README.

Our eventual goal is to make each exercise on GitHub stand-alone. What you see is what you get. All the files that we deliver to the user will be in that directory. We're not quite there yet. For now we're focusing on making sure that each exercise has a README which is committed to the track repository.

Making this change forces some consequences onto maintainers:

1. Shared metadata is now technically a starting point. You can veer away from it if that makes sense in your programming language.
2. In order to avoid a lot of manual and error-prone copy/pasting, we need tooling to generate these READMEs. They can be re-generated at any time in order to incorporate changes that happen in the shared problem specification repository or to the shared/default files in the track repository.
3. Because part of the point is to allow customization, we now need a readme template that each exercise can use.
4. Since most exercises will likely have the same structure, it makes sense to have a default template. Then exercises would only have their own README template if they want to deviate from the default.

We need to make a decision about where to put the track-level default README template. While we're at it, we can reconsider all the names and locations of other README-relevant files. There are quite a few:

• Files that comprise the problem specification. These might live in the problem-specifications repository (exercises/:slug/:file), or they could live within the track repository (exercises/:slug/.meta/:file). The README generator will look in the track first, then in the problem specifications repository, so a track can override the metadata if desirable.
  • description.md
  • metadata.yml
• Track-level text to be included in all exercise READMEs
  • docs/EXERCISE_README_INSERT.md
• Exercise-specific text to be included in a given exercise
  • exercises/:slug/HINTS.md
• Track-level default README template
  • ??? readme.go.tmpl
• Exercise-specific README template (overrides the track default)
  • exercises/:slug/.meta/readme.go.tmpl

My current opinion is that the description.md and metadata.yml are named correctly, and live in the right place.

HINTS.md is probably named fine, though I might be happier with hints.md. However... I don't think it should live in the root of the exercise directory as it currently does. I think that this belongs in the .meta directory. My suggestion would be .meta/hints.md.

I think the exercise-specific README template is fine in .meta/readme.go.tmpl.

I think that docs/EXERCISE_README_INSERT.md is in the wrong place (I know I argued for putting it in docs before, but it's kept bugging me, and I think it doesn't belong there.

I don't know where to put the track-level README template, but having thought about it a bit and discussed it with @petertseng, I think that the right approach would be to create a new directory at the root of the track, which would contain both the default README template, and the track-level exercise README insert.

So we need to decide:

1. Should we have a top-level directory for the track-level exercise data and defaults?
2. If so, what should such a directory be named? (.exercise? meta?)
3. If we move EXERCISE_README_INSERT.md to a file that is all about track-level exercise things, should we rename it?
4. If so, what should it be called? (E.g. readme-insert.md?)
5. Shall we move HINTS.md to .meta?
6. Shall we rename HINTS.md?

/cc @exercism/track-maintainers as this is relevant to you all.

[kytrinyx]

Having slept on this, how about a boilerplate directory in the root of the track repository, that would contain exercise-readme.go.tmpl and exercise-readme-insert.md?

[ErikSchierboom]

I'm not really sold on boilerplate. To me that makes it sound like its boring, uninteresting data, which I don't think fits with the contents.

1. Should we have a top-level directory for the track-level exercise data and defaults?
   Yes

2. If so, what should such a directory be named? (.exercise? meta?)
   .meta

3. If we move EXERCISE_README_INSERT.md to a file that is all about track-level exercise things, should we rename it?
   Yes

4. If so, what should it be called? (E.g. readme-insert.md?)
   exercise-readme-insert.md

5. Shall we move HINTS.md to .meta?
   Yes.

6. Shall we rename HINTS.md?
   Yes (to hints.md)

[kytrinyx]

I like all of these answers, @ErikSchierboom

[wobh]

Recognizing the README and HINTS documentation as products requiring configuration data suggests a couple of things. I don't think anyone is considering internationalizing this documentation, but it might be useful in the short run to pretend we were. What then?

Some shots from the hip.

1. Maybe?
2. config, conf, or cfg (maybe even var or etc if you're feeling *nixy)
3. Sure.
4. cfg/readme.yml
5. Sure.
6. cfg/hints.yml

[petertseng]

If so, what should such a directory [top-level directory for the track-level exercise data and defaults] be named? (.exercise? meta?)

Whatever it is, my preference is that its first character not be ..

My reason for the preference is that I want it to show up in tab completion without me having to type . first. As a specific example where this hurts me, in https://github.com/exercism/ruby/tree/master/exercises/accumulate the only subdirectory is .meta, so if I type cd <tab> I expect to get .meta completed but instead I get No matches for: `local directory' (and nothing gets inserted by tab-complete), and so I am forced to type cd .<tab> instead.

It will make me slightly happier, but nobody is obligated to make me happy, so consider my preference safely ignorable. If the directory name does end up starting with ., I plan to make a symlink from .name to name (so don't write code that will break if name exists).

I guess I would call the directory config if you asked me.

[kytrinyx]

I don't really think we need to make the directory hidden at the top level of the repository.

In the exercises it makes more sense, because the goal is to make these directories the only thing that is not delivered to the user, so if you look at the exercise directory, everything that is not hidden, should be the exercise.

[Smarticles101]

1. No. We should put them under docs in a new folder defaults
2. Yes
3. readme-insert.md or README-INSERT.md
4. Yes
5. Maybe to hints.md

[kytrinyx]

@Smarticles101 I'm not convinced about putting them in docs, but I'm not sure that I have a good reason.

I'm going to try to put words to this somewhat amorphous feeling.

Right now, aside from the EXERCISE_README_INSERT.md file, everything in docs is user-facing, track-level documentation. The readme insert and the readme template are both used as part of the generation process for exercise-level instructions. I can see how exercise-level instructions could be classified as docs, but these things feel different to me. Further, both of the exercise-level files are consumed by a tool that the maintainers run, which make them feel even more different to me—they're materials rather than end-products.

[kytrinyx]

OK, I've still not heard a definitive winner.

So far my votes are:

• a directory at the top level
• not hidden
• named meta or config (?)
• exercise_readme.go.tmpl, exercise-readme-insert.md for the files in that directory
• hints.md and readme.go.tmpl for the files in exercises/:slug/.meta/

Notice: snake_case for Go files, caterpillar-case for markdown files.

@Smarticles101 @ErikSchierboom @wobh @petertseng -- so far you are the ones who have had opinions. Any last thoughts? If not I'll flip a coin on the directory name and submit PRs.

[petertseng]

It remains true that I have decided to trust your judgment on all matters I did not express an opinion on

[Smarticles101]

Naming the folder `meta` sounds great to me.

…

On Fri, Jul 14, 2017 at 12:23 PM Peter Tseng ***@***.***> wrote: It remains true that I have decided to trust your judgment on all matters I did not express an opinion on — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#165 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ALBZq1R26b2BSk1LRVIFRWcxhHgXDS6uks5sN6QTgaJpZM4OTrRM> .

[tleen]

'meta' allows for more than just configuration info should the need arise. It is a more general term for stuff about the exercise.

[kytrinyx]

@tleen that's a good point.

OK, that's the winner. I will make it so today! Expect pull requests in your inboxes 🎉

[wobh]

I'm content to be overruled, however I do wish to file this dissent: To me, meta seems too general, it's not clear to me what belongs in there. Is that a convention used elsewhere?

Generalizations, I feel, need some reasonable hypothetical examples to assess. What non-configuration data would one put in there? Does it make sense to put it with configuration data?

Here's one: If some exercises in a track were to require some shared, non-textual assets (images, diagrams, audio, video), what makes meta "better" for contributors than a config, assets sort of split?

As I said, I'm content to be overruled. The questions above may be treated as rhetorical.

[kytrinyx]

Generalizations, I feel, need some reasonable hypothetical examples to assess.

Given your examples, I think we would end up with several less-generalized and more expressively named directories. Which I like.

You changed my mind.

I'm going to finish the configlet PR, then wait a day so we can allow for more counter-arguments, then finalize with a decision.

[tleen]

Here's one: If some exercises in a track were to require some shared, non-textual assets (images, diagrams, audio, video), what makes meta "better" for contributors than a config, assets sort of split?

An "assets" directory as described would be part of the exercise (if users needed it to complete the exercise) and not belong in a .meta dir? On the other hand if every exercise had, say, an icon associated with it, that would belong in a meta directory as an asset. Ideally we would want to avoid a proliferation of directories.

If it came to splitting up items in the exercise that were not directly related to doing the exercise itself I would think because .meta/config and .meta/assets would make semantic sense while keeping everything one directory. "meta" really meaning "stuff about the exercise, but not the exercise itself" so it can hold whatever that is not part of the actual exercise. "config" can mean this too, but "meta" would be a more correct term for it?

The whole thing is splitting hairs really. It could just as soon be named .other-stuff-we-would-rather-the-users-not-see-but-we-need-for-exercise-generation/ and still function as envisioned. Don't use that name though 😆

[kytrinyx]

Alright. I'm going to go with config, since at the moment we don't know that we need to expand this. If we do, I'm happy to do the work to rename etc if it makes more sense at that time.

I'll be using exercism/meta#15 as a tracking issue for all the README generation.

Thanks everyone!