[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/)

• 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".

• LEARNING.md:

  details

  • Line 9: "exercism" should be capitalized.
  • Line 19/42: This link is the same as the non-workbook one. It should be a link to the workbook's page: https://inventwithpython.com/automate3workbook/
  • Line 24/52: This seems to be a link to a "live" version, it is now a recorded class at: https://lernerpython.com/courses/python-for-non-programmers/
  • Line 25/36: This link now redirects to: https://learnxinyminutes.com/python/
  • Line 29: "Googles" should be "Google's".
  • Line 30/37: This learning path seems to no longer exist. The closest things I can find are Microsoft's Python for Beginners and Python Development Professional Certificate.
  • Line 31/49: This link now redirects to: https://ocw.mit.edu/courses/6-0001-introduction-to-computer-science-and-programming-in-python-fall-2016/

• 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)".

• RESOURCES.md:

  • Line 14/26: This link now redirects to: https://blog.pythonlibrary.org/

• TDD.md:

  details

  • Line 7: It isn't completely clear what "implementation-specific design" means.
  • The paragraph on lines 5-12 is rather long and would benefit from being split up, perhaps into smaller paragraphs or a list.
  • Lines 18-19 are rather confusing. Perhaps they could be changed to something like: "Although it is sometimes called 'refactoring' to modify code to get it to pass the tests, this is only actually 'refactoring' if it improves the design of the code. Simply debugging without improving the design is not refactoring."
  • Troubleshooting a Failed Test on Exercism in the Web Editor section:
    • Line 78 (and others): "Test 1 is usually going to be a kind of template with a code section for setting up the tests" seems to no longer be true. Any template/setup seems to no longer be shown to the student.
    • Line 92-93: The tests no longer have the inputs and outputs in the headers. This should just be "FAILED TisburyTreasure > get coordinate [variation #1]".
    • Line 99: Is "likely" necessary? I can't think of a case where the information is not shown in a code section.
    • Line 100: Are there actually any cases where the tests share the data?
    • Line 110: It isn't entirely clear that this is a continuation of the example. Perhaps it could be changed to: "In this example, the problematic code is as follows:" or "The code for get_coordinate() here might look like the following:"
    • Since the whole section is about concept exercises, and most of the ideas apply to all exercises, it should include a sentence like: "This section only covers concept exercises, but the process is very similar for practice exercises."
  • Line 140 is a bit awkward, maybe it could be: "If a mentor is available, they may contact you with ideas for improvements or other approaches."
  • Line 145: A link to a source with more context would be helpful here.
  • Line 154 is confusing. Maybe it could be changed to: "The more times the stmt code is run, the less the setup time will count towards the result."
  • The paragraph on lines 145-159 is very long and would benefit from being split up.
  • Line 175 is an unnecessary blank line. Having a blank line after line 179 instead would probably improve readability. (This also applies to the next code block on lines 187-202.)
  • In the last two codeblocks, the usage of quotes is inconsistent. VOWELS = "AEIOU" should probably be changed to VOWELS = 'AEIOU'.
  • The links to "www.agilealliance.org" and "www.machinelearningplus.com" now redirect to "agilealliance.org" and "machinelearningplus.com" respectively.

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.

[Yrahcaz7]

@BethanyG, is docs/SNIPPET.txt used anywhere? I'm skipping the file for now because its purpose is unclear.

[BethanyG]

@Yrahcaz7 - not that I know of, so its ok to skip. Thanks!