Many minor fixes

[Yrahcaz7]

@BethanyG, sorry in advance -- I know reviewing this will take some work. Turns out there was a bunch of single hyphens that should have been em-dashes and my brain went into ADHD mode from there. Ended up fixing a lot of unrelated small things 😆

Full changelog:

Fixed some em-dashes that were actually hyphens, a few terms that were missing backticks, some indentation errors, one codeblock that didn't have closing triple-backticks, a few invalid links, some minor spacing errors, a few typos, one missing level-one header, one level-three header that should be a level-two header, one incorrectly wrapped paragraph, a few "-->"s that would be more clear as "to"s, a few headers that weren't surrounded by blank lines, one incorrectly placed ref-link, and one level-two heading that should be a level-one header.

[BethanyG]

@Yrahcaz7 - I am sorry - but this is waaaaaay too many files changed in one PR.

Please don't take this personally — I really appreciate all the hard work. But I think the ADHD has gone too far here.

And I don't have confidence that I can catch if you made any mistakes in pulling previous changes in. It is PRs like this that led to so many typos previously. It is very hard for the humans to track what's going on.

And I am really not fine with all the em-dash replacement. I think we need to live with not replacing all of the single dashes. First, because it makes things look like they were written by AI, and second because we run the risk of introducing so many changes we actually "crapify" the things we've already been over. Again, even with good diff tools the through-line gets lost.

So. My recommendations:

1. Back out the current single dash to em-dash changes. I know that will feel painful, but they need to be set aside for now. Maybe forever. Most folx cannot tell the difference, and really it is -- that was in sore need of conversion. This is just not the quest we should be on.

2. I'd strongly prefer any current changes short of things like unclosed code blocks, or outright syntax or spelling errors be backed out of any concept docs we've already touched. I know I said that we could loop back for some things, but we've already been through these docs multiple times (once for you to log, once for me to change, once more for you to review the change), and we are pulling focus from much more important things like creating more approaches and getting new exercises and new syllabus entries done. Not to mention docs we haven't reviewed yet. We can possibly revisit previous docs after a month or two cooling off period. But for now, done is done for concept docs — as painful as that stray space indent or missed backtick is. Perfection is not the goal, and isn't achievable here anyways.

3. Ditto for concept exercise docs. Whenever we update a concept exercise, a notification goes off on the website for students to update their exercise files. We really need to not make it highly irritating for students. So unless it is a really bad issue, we need to not push changes to a lot of concept exercises at once. I had to do that for the Python upgrade and got flamed. I don't want the same hassle because we inserted some em-dashes or backticks. Bad or confusing things can be discussed, but small format changes probably need to wait.

4. Finally, I can't effectively review 66 files across dozens of concepts, exercises, and other docs. Context matters — I am a much more effective reviewer when I know that what I am reviewing is related, and that I can "finish up" a task and take a break. Reviewing this would take me hours, and I would be likely to lose focus. And if there was a mistake, it is much MUCH harder to revert and correct when there's so much to go through. Smaller and more isolated PRs are just much easier to revert and redo. So I'd like changes after the points above are addressed to be broken up:

   • Any concept doc changes should be in their own PR. Preferably with [Concept Docs Errors] in the title.
   • Any concept exercise changes should be grouped in their own PRs, with the title of the exercise(s) in the PR title. No more than three concept exercises per PR, and probably less than that. That way, if there is a problem with an exercise, the PR can be easily searched for and found by title.
   • I don't really want more than 2-3 exercises (when it comes to their approaches) in a single PR either. Especially since there are so many approaches docs per exercise. And again, much easier to identify these when they include the exercise name in the title.
   • The general docs are their own thing, and they should be in their own PR. These (as you've seen) are hefty and they take time to re-read. These also should have the names of the docs in the PR title.

And sometimes, I would like the opportunity to do corrections. It is helpful to me to see where I make mistakes and what patterns are there. And also? Making a PR is 12 rep points, but reviewing (which can sometimes be every bit as much work) only carries 5 rep. So there is that as well.

I hope I am not coming off as too harsh — I am just trying to stay sane as a sole maintainer. Thanks for your help, and for your understanding. 🙂 💙

[Yrahcaz7]

I understand, I should have thought things through a bit more. I'll have to really imprint "context matters" into my brain.

Whenever we update a concept exercise, a notification goes off on the website for students to update their exercise files.

I didn't know that... I thought it was only when the tests changed. It definitely makes sense to not bother with small formatting changes then.

So I'd like changes after the points above are addressed to be broken up:

Tomorrow I think I'll try to pick out the few fixes that are actually important, and break those up into their own PRs (one PR per concept/exercise).

Sorry for the trouble - And thanks for telling me what the problems are and how I can improve!

[BethanyG]

I understand, I should have thought things through a bit more. I'll have to really imprint "context matters" into my brain.

I hope I didn't come off as yelling at you. Make no mistake: you've contributed a tremendous amount to the track, and that is really really appreciated. 😄

As I said in my Discord message, I am dealing with a project that is almost at polar opposites to the Python repos. I have these unholy markdown files to deal with (I can show you an example on Discord), and some pretty wild CSS and JS to deal with as well. I also have a bunch of cross-track Exercism stuff, and things like GH action files and docker files. So my brain (which isn't very large to begin with) is having to do even more context switching than usual. 😅

But if you also take a look at closed PRs, you'll see that there are .... a LOT. It doesn't feel like a lot when you are making them (and the intent seems clear from the code). But walk away for 10 minutes or try to do something else in a different track or programming language or project ... well, coming back and trying to figure things out is rough. So I've gotten hyper about tagging things to make sure they're idiot-proof(ish) — because that idiot is me.

I didn't know that... I thought it was only when the tests changed. It definitely makes sense to not bother with small formatting changes then.

Let me ....double check that. I might be getting it wrong. But I think my critique still stands: we've gone over all of theses, and run the risk of getting stuck in a loop or worse — screwing up something we've already edited. So I'd pick the important changes there.

Sorry for the trouble - And thanks for telling me what the problems are and how I can improve!

💙 You are not bad trouble — you are good trouble. 😄 I'd rather spend time doing this than dealing with ... well, with a lot of other things. 😉

[Yrahcaz7]

Opened a PR for the functions concept fixes: #4234. It seems like this one had the majority of the important fixes.

Everything else is more spread out, and I'm not sure if they are important enough for a PR:

• For docs/PROBLEM-SOLVING.md, the only important fix seems to be correcting the title "The Programmers Brian" to "The Programmer's Brain".
• exercises/concept/black-jack/.docs/introduction.md seems to be missing a level-one header. Similarly, exercises/practice/yacht/.approaches/functions/content.md has a level-two header instead of a level-one header.
• exercises/concept/mecha-munch-management/.docs/introduction.md line 7 seems to have a level-three header when it should be a level-two one.
• exercises/practice/nth-prime/.approaches/tracking/content.md has a link-ref that is outside of the ~~~~exercism/advanced block that it is used in, so the website doesn't pick up the link.

[BethanyG]

For docs/PROBLEM-SOLVING.md, the only important fix seems to be correcting the title "The Programmers Brian" to "The Programmer's Brain".

🤔 Wonder if it is worth it to maybe group this with other (potential) edits to other general docs? In particular, the TRACEBACKS has alway felt like it needed a real going-over and reorganizing. It just doesn't feel helpful at a student level. But that may be me.

And there are the other docs in that folder. GENERATOR hasn't been touched in 3 years, and TDD (which is hard for me to even read) hasn't been touched in 4. And I haven't looked at TESTS in a while, so I am sure there are version and syntax things that might be outdated there. INSTALLATION might also need some updating or love. I often lose track of the "most current method" of Python setup.

There are also a few analogues to these docs in the shared directory. I say analogue, because the files there are designed to be downloaded when a student uses the Exercism CLI, so they're formatted differently, IIRC.

Some other general docs include CONTRIBUTING (which ... ooof ... is a LOT), and the README. But proceed with some caution there: there is a lot of embedded HTML and other nasty markdown tricks and a crap-ton of emoji. It may be time to redo CONTRIBUTING altogether.

BUUUT. It is also fine to take a break from all this reviewing. If it's too much to go through these last docs, I am happy with you making a PR to just change the link. We can flag it small (5rep) and ... just get it done. Totally up to you. 😄

exercises/concept/black-jack/.docs/introduction.md seems to be missing a level-one header. Similarly, exercises/practice/yacht/.approaches/functions/content.md has a level-two header instead of a level-one header.
exercises/concept/mecha-munch-management/.docs/introduction.md line 7 seems to have a level-three header when it should be a level-two one.
exercises/practice/nth-prime/.approaches/tracking/content.md has a link-ref that is outside of the ~~~~exercism/advanced block that it is used in, so the website doesn't pick up the link.

So let's do this:

• One PR for the concept exercise changes (that's Black Jack and Mecha Munch)
• One PR for approaches (that's nth prime and yacht)

I am happy with you doing one, both, or none.

Does all that make sense? Just let me know. 😄

[Yrahcaz7]

Does all that make sense?

It does!

Wonder if it is worth it to maybe group this with other (potential) edits to other general docs?

Probably, but there's a lot of general docs, so it might be worth making a new tracking issue and batching small changes together and leaving big ones by themselves (similar to the Typo Patrol issue).

[BethanyG]

Probably, but there's a lot of general docs, so it might be worth making a new tracking issue and batching small changes together and leaving big ones by themselves (similar to the Typo Patrol issue).

Makes sense to me! Do you want to do that, or shall I? I won't be quick (I am in an epic battle with a crappy IDE at the moment) - but I will do it by the end of the week. 😄

[Yrahcaz7]

I'll create the issue with my initial PROBLEM-SOLVING.md fix, and either of us can add to the issue later. I'll probably be slow in reviewing the docs, though, as I still need to finish the Eliud’s Eggs approaches.

[Yrahcaz7]

Opened the issue here: #4237