Gentler on-ramp for people creating and maintaining new tracks

[gitonthescene]

While one can certainly piece together from this project's name and by poking around a bit how this project might be useful, the README seems to dive right as thought readers already understand the thought that went into it. I wonder if it would useful to add more prose to this and maybe even add some indication of a general pedagogy behind these problems to put track designers on the right road.

I wasn't around for the discussions that went the start of this, but I'm happy to create a pull request as a starting point for the discussion if that seems like a good idea.

[gitonthescene]

For background, I found out about it because someone described the python track as auto-generating tests from this data and I was trying to understand the mechanism. Whether that's correct or not, it may point to a need for more specific guidance.

[kytrinyx]

@gitonthescene I agree 100%.

This sort of guidance should go into the exercism/docs repository, which gets rendered on the website here: https://exercism.org/docs
There's a whole section dedicated to building a new track, which I think we could flesh out quite a bit:
https://exercism.org/docs/building/tracks/new

It's possible that the README of this repository could even say less, but point directly to the most useful parts of the documentation on the Exercism website.

If it works for you we could use this issue to hash out some bullet points of what is confusing, what's missing, and poinpoint some of the answers, before we make some pull requests to fix it.

[gitonthescene]

I’m happy to have a reference to more explicit documentation but I do believe some statement of purpose for is valuable for any repository. I certainly don’t think saying less than “Shared metadata for Exercism exercises.” would be useful.

The new track documentation is fine for what it is but I believe expecting everyone to follow the exact same steps to acquire knowledge is a mistake. There should be breadcrumbs left throughout to guide people through the process for people who approach it from different angles.

I’ve explained above how I arrived here. I don’t think I’m the first person to be a bit put off by trying to understand something and being directed to a manual. If this is meant as a barrier to entry then it’s probably fine as it is.

[gitonthescene]

Here’s what I might put:

Repository for exercises to be used across tracks. This includes both problem statements available as html and test data described below.
Note that tracks are not required to use these exercises and some may be more or less appropriate to the given language.

See the new track roadmap for full details on setting up a new track.

[kytrinyx]

Sorry, I misunderstood what you meant in the initial post. There's quite a lot of documentation that is missing with respect to this repository, and I was trying to avoid having you do a bunch of work and submit a novella to the README here, only to have 200 maintainers descend upon your PR and argue about which bits belong where.

What you have above seems like a good improvement. I would suggest

problem statements available as markdown

rather than as HTML.

[gitonthescene]

Thanks. Should I submit that as PR?

FWIW, I know making good documentation is hard and the finding consensus is often harder. I often try to find places for incremental improvement which hopefully serve as a model for best practice.

[kytrinyx]

Yes, please do submit this as a PR!