[General Docs] Audit/Cleanup of Track General/Shared Docs

[Yrahcaz7]

This is a tracking issue for errors in the general docs on the Python track.

The docs are split into the below categories (general, shared, and other) depending on their location in the repo.

General Docs (docs/)

• PROBLEM-SOLVING.md (addressed in PR 4253):

  details

  • Line 4: Maybe italics or bold should be used instead of backticks.
  • Line 12: There should be a space after the comma.
  • Line 16: "The Programmers Brian" should be "The Programmer's Brain"
  • Line 18: There is two question marks in a row when there should be only one.
  • Line 19/30: The first link ("https://nostarch.com/algorithmic-thinking") now redirects to "https://nostarch.com/algorithmic-thinking-2nd-edition".
  • Line 20/40: The second link ("https://www.amazon.com/Computational-Thinking-Problem-Textbooks-Computing-ebook/dp/B00IZL9NQI") gives a 404 Not Found. It seems like there is a physical book version, though.
  • Line 20: There shouldn't be a period after the second link, the text after is part of the same sentence.
  • Line 21/42: The link seems to have a useless query string that may be used for tracking. This should be removed, giving the clean link.
  • Line 23: The acronym for "Association of Computing Machinery" should probably be mentioned, maybe written as "Association of Computing Machinery (ACM)".

• ABOUT.md (addressed in PR 4254):

  details

  • Line 10/51: The "psf" link ("https://www.python.org/psf/") now redirects to "https://www.python.org/psf-landing/".
  • Line 10/49: The "peps" link ("https://www.python.org/dev/peps/") now redirects to "https://peps.python.org/".
  • Line 10: "Python Enhancement Proposals or PEPs" would be more clear that it is saying two different names for the same thing if it was written as "Python Enhancement Proposals (PEPs)".
  • Line 11: "persuasions" appears to be a typo, was it supposed to be "professions"?
  • Line 15: "(Jupyter notebook)" should probably be "(or Jupyter Notebooks)".
  • Line 20/62: "the zen of python" link ("https://www.python.org/dev/peps/pep-0020/") now redirects to "https://www.python.org/dev/peps/pep-0020/".
  • Line 20/64: The "what is pythonic" link ("https://blog.startifact.com/posts/older/what-is-pythonic.html") now redirects to "https://blog.startifact.com/posts/what-is-pythonic/".
  • Line 23: It is not immediately obvious that "3.10 - 3.13.5" refers to Python version numbers, "Python" or "version" should probably be added to clarify.

• GENERATOR.md:

  details

  • Lines 7 to 18: Was this table of contents automatically generated by a tool? If it was manually created (or if it is possible to configure the tool otherwise), the top-level header "Exercism Python Track Test Generator" should probably be excluded.
  • Line 40: The word-count additional tests path has changed, it is now exercises/practice/word-count/.meta/additional_tests.json
  • Line 45: The example is missing a % at the end of the if statement. It should be: {% for case in cases %}{% if case is error_case %}
  • Line 54: The footer macro no longer exists. This should be probably be changed to mention macros.canonical_ref() and/or macros.header() instead.
  • Line 60: "option file" should be "optional file"
  • Lines 60-61: The wording here is a bit awkward, maybe "is to have" could be changed to "should have"?
  • Lines 60-62: The second sentence should be on its own line.
  • Lines 71-90: This part seems outdated; it uses the footer macro that no longer exists. It should probably be updated based on master_template.j2.
  • Line 95: There should be a space after the "ex:"
  • Line 98 would be more readable if there was a space between the ) and the }}, like so: "{{ macros.header(["Clock"]) }}".
  • Line 122: "templates" should be "template" here.
  • Line 131: This inline link should be converted into a reflink.

• INSTALLATION.md:

  details

  • Line 15: There should be punctuation in between "Windows" and "Additionally".
  • Line 16 is missing a period at the end.
  • Line 19: Is this line supposed to be indented? It doesn't seem to be a continuation of the last list item.
  • Line 22: Python 3.13.5 should be Python 3.13.13.
  • Lines 24-25 are a bit awkward, maybe they could be merged into one sentence: "Most of the exercises will work with Python 3.6+ or even earlier versions, but we don't guarantee support for versions not listed under Active Python Releases."
  • Lines 32-33 and 34-35: These pairs of reflinks are the same. Is this intentional?
  • Line 38: This link now redirects to "https://learn.microsoft.com/en-us/windows/dev-environment/python".

Shared Docs (exercises/shared/.docs/)

TBA

Other (CONTRIBUTING.md, README.md)

TBA

[github-actions]

Hello. Thanks for opening an issue on Exercism 🙂

At Exercism we use our Community Forum, not GitHub issues, as the primary place for discussion. That allows maintainers and contributors from across Exercism's ecosystem to discuss your problems/ideas/suggestions without them having to subscribe to hundreds of repositories.

This issue will be automatically closed. Please use this link to copy your GitHub Issue into a new topic on the forum, where we look forward to chatting with you!

If you're interested in learning more about this auto-responder, please read this blog post.

[Yrahcaz7]

@BethanyG, I finally got around to auditing two general docs: PROBLEM-SOLVING.md and ABOUT.md. Could you reopen this issue?

[Lucifer-ipynb2]

Hi! I'd like to work on the README.md audit. Please let me know if it's available. Thanks!

[BethanyG]

@Lucifer-ipynb2 ,

Thanks for the offer, but right now we only have the capacity for one core contributor, and that's @Yrahcaz7 . I am sorry - but I just don't have the review and mentoring capacity for anyone else at the moment. I will let you know if that changes.

[hugo-labs-77]

It seems like the audit for PROBLEM-SOLVING.md has identified multiple issues, particularly with links and grammar. Regarding the second link that returns a 404 error, it might be worth checking if there's a newer version of the resource that can be linked instead. Also, can we confirm whether the changed link for "Algorithmic Thinking" correctly reflects the latest edition? A redirect might not be the best user experience if users are directed to outdated content.

[BethanyG]

@hugo-labs-77 - Thanks for the comment. We'll keep that in mind as we go to PR this.