Repository navigation
Gentler on-ramp for people creating and maintaining new tracks #2120
Description
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.
Activity
gitonthescene commentedon Oct 8, 2022
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 commentedon Oct 8, 2022
@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 commentedon Oct 11, 2022
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 commentedon Oct 11, 2022
Here’s what I might put:
kytrinyx commentedon Oct 11, 2022
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
rather than as HTML.
gitonthescene commentedon Oct 11, 2022
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 commentedon Oct 11, 2022
Yes, please do submit this as a PR!