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

**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/`](https://github.com/exercism/python/tree/main/docs))

- `ABOUT.md` (addressed in [PR 4254](https://github.com/exercism/python/pull/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. It should also use `-` for all the list elements as per [the docs](https://exercism.org/docs/building/markdown/markdown#h-lists).
- 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.
- Line 66: There should probably be a blank line before this codeblock.
- 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 126: `#Layout` should probably be `#layout`.
- 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](https://www.python.org/downloads/)."
- 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](https://learn.microsoft.com/en-us/shows/intro-to-python-development/) and [Python Development Professional Certificate](https://www.coursera.org/professional-certificates/microsoft-python-developer).
- 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](https://github.com/exercism/python/pull/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](https://www.amazon.com/Computational-Thinking-Problem-Textbooks-Computing/dp/1466587776), 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](https://www.amazon.com/Computing-Computational-Thinking-Paul-Wang-dp-1482217651/dp/1482217651).
- 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](https://github.com/exercism/python/blob/main/docs/TDD.md#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](https://softwareengineering.stackexchange.com/a/80092) 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.

- `TESTS.md`:

details

- Line 3/263: This should probably link to the "stable" version of the docs, not the "latest" one: https://docs.pytest.org/en/stable/getting-started.html
- Line 10/269: This link now redirects to: https://pylint.pycqa.org/en/latest/user_guide/installation/index.html (however, the stable version should probably be linked instead: https://pylint.readthedocs.io/en/stable/user_guide/installation/)
- Line 13/278: The first link is to a very old version of pylint, it should probably link to the stable docs instead: https://pylint.readthedocs.io/en/stable/tutorial.html
- Line 22: `Python3` should be `python3`.
- Lines 31, 38, and 46: The required `pytest` version now seems to be `8.4.x`.
- Line 94/265/279: These links are to a very old version of the pylint docs, they should probably link to the 8.4.x docs instead: https://docs.pytest.org/en/8.4.x/how-to/mark.html#raising-errors-on-unknown-marks and https://docs.pytest.org/en/8.4.x/example/markers.html#working-with-custom-markers (respectively).
- Line 96/264: Similar to the previous line, the link should be https://docs.pytest.org/en/8.4.x/reference/customize.html#configuration-file-formats
- Line 96 is missing a period at the end.
- Line 101: "an" should be "a" here.
- Lines 130, 132, and 134 have many outdated versions.
- Line 189: `path/to/exercise` is a different format than all of the other placeholders. It should probably be `` instead.
- Line 204/266: This link is to an old version of the python docs. It should link to the latest supported version: https://docs.python.org/3.13/library/pdb.html
- Line 213/271: The first link is to an old version. In the `8.4.x` docs, this section is here: https://docs.pytest.org/en/8.4.x/how-to/failures.html#dropping-to-pdb-on-failures
- Line 213: The second link is inline. It should be converted to a reflink.
- Line 217: This link should be a reflink. It also does not work on GitHub, so it should just always link to the Exercism website: https://exercism.org/docs/tracks/python/tools
- Line 218 is missing the oxford/serial comma.
- Line 240: The comma should be after "Next" instead of "press".
- Line 242: This alt-text does not describe the image at all. (The alt-texts on lines 246 and 250 could also be improved, but those are less important than this one.)
- Line 256 should have punctuation at the end.

- `TOOLS.md`:

details

- Overall
- The headers have (probably) unnecessary `` links.
- Some link texts are not descriptive, such as on lines 220, 274-276, 292, 295, 299, and 371.

- Top Level
- Line 9: Is it still recommended to do this directly on GitHub, or should this point to the forum instead?

- Virtual Environments
- Line 55: The first link is to the docs for an unsupported Python version, it should be the latest supported one instead: https://docs.python.org/3.13/tutorial/venv.html
- Line 55: The second link is to the "latest" version, it should probably link to the "stable" version instead: https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/manage-environments.html
- Line 58: The last link is to the "latest" version, it should probably link to the "stable" version instead: https://virtualenvwrapper.readthedocs.io/en/stable/

- Creating a virtual environment with `venv`
- Line 69 and 83: These should probably be level-four headers instead of bold text.
- Line 98: "`venv`s" should be "`venv`'s" and "`{name_of_virtual_env}/Lib`" should be "`{name_of_virtual_env}/lib`".

- Creating a Virtual Environment using `conda`
- Line 106: This link now [redirects here](https://www.anaconda.com/docs/getting-started/concepts/anaconda-or-miniconda). However, I am not sure if this has the same content as the original link, and [this page](https://continuumio-docs.readthedocs-hosted.com/miniconda/) looks more relevant.
- Line 107: The first link 404s, it should be updated to: https://docs.conda.io/projects/conda/en/stable/user-guide/cheatsheet.html
- Line 107: The second link is to the "latest" version; it should probably link to the "stable" version instead: https://docs.conda.io/projects/conda/en/stable/user-guide/
- Line 109: This link now [redirects here](https://www.anaconda.com/download).
- Line 113: This link now [redirects here](https://docs.conda.io/projects/conda/en/latest/commands/index.html#conda-vs-pip-vs-virtualenv-commands), but the stable version should probably be used instead: https://docs.conda.io/projects/conda/en/stable/commands/#conda-vs-pip-vs-virtualenv-commands

- UV
- Line 220/467: This link doesn't have descriptive link text. Instead of `Working on Projects with uv: [uv][uv-docs]`, it should be something like `Here is the uv docs on [working on Projects with uv][uv-docs].` The "uv-docs" reference is also confusing, it should be something like "uv-working-on-projects" instead.

- PyEnv
- Line 238: This link no longer has a "plugins" heading. If it was the top-level header, this [link to the stable docs works](https://virtualenvwrapper.readthedocs.io/en/stable/plugins.html#extending-virtualenvwrapper).

- Editors and IDEs
- Line 255: Not that important, but this separator uses `______` instead of the `---` used elsewhere in the document.

- Visual Studio Code
- Line 262: The page that the second to last link goes to no longer has a "\_formatting" header. It seems to have been extracted into [its own page](https://code.visualstudio.com/docs/python/formatting).
- The first link on lines 270/ and 272/ are the same but use different reflinks.
- Line 272: The other extensions are now [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance), [Python Debugger](https://marketplace.visualstudio.com/items?itemName=ms-python.debugpy), and [Python Environments](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-python-envs).

- PyCharm
- Line 283: There is a space before the period.
- Lines 289-297: Because the collapsed `` element looks similar to a list item, it is unobvious that it can be expanded. It should probably be a nested list instead.
- Line 294: The second link should be a reflink and also point to the Exercism website: https://exercism.org/docs/tracks/python/tests#h-extra-arguments

- Spyder IDE
- Line 313: `kite` seems to be no longer maintained. Is this statement still valid?
- Line 323: This heading ([`updating-spyder`](https://docs.spyder-ide.org/current/installation.html#updating-spyder)) seems to have been split into [`updating-a-standalone-install`](https://docs.spyder-ide.org/current/installation.html#updating-a-standalone-install), [`updating-with-conda`](https://docs.spyder-ide.org/current/installation.html#updating-with-conda), and [`updating-with-anaconda`](https://docs.spyder-ide.org/current/installation.html#updating-with-anaconda) sections.
- Line 332: This heading ([`anaconda`](https://docs.spyder-ide.org/current/installation.html#anaconda)) seems to have been renamed to [`anaconda-base`](https://docs.spyder-ide.org/current/installation.html#anaconda-base).
- Line 333: This heading ([`new-conda-environment`](https://docs.spyder-ide.org/current/installation.html#new-conda-environment)) seems to have been renamed to [`conda-environment`](https://docs.spyder-ide.org/current/installation.html#conda-environment).
- Lines 337, 338, and 340: This links to an old version of the docs, it should link to the [current version](https://docs.spyder-ide.org/current/faq.html) instead. ([Link for line 338](https://docs.spyder-ide.org/current/faq.html#using-existing-environment) and [Link for line 340](https://docs.spyder-ide.org/current/faq.html#using-plugins).)

- Emacs
- Line 349: This doesn't seem to link to the right header anymore, as the page's headers use numbers instead descriptive names. It should probably just point to the [top of the page](https://www.emacswiki.org/emacs/PythonProgrammingInEmacs) with the table of contents instead.

- Vim
- Line 358: The third link 404s, it has been [moved to here](https://glump.net/howto/desktop/vim-graphical-cheat-sheet-and-tutorial/vi-vim-cheat-sheet-and-tutorial.pdf).
- Line 361: Here, "familiarise with" should be "familiarize yourself with".
- Line 363: This link now [redirects to here](https://stackoverflow.com/questions/11828270/how-do-i-exit-vim).

- Spacemacs
- Line 371 does not have punctuation at the end.

- Sublime text
- Line 380: The second link now redirects to a [blog post about sunsetting Atom](https://github.blog/news-insights/product-news/sunsetting-atom/).
- Lines 383-388: Some of these list items end with punctuation, while some do not.
- Line 387: This link now [redirects here](https://realpython.com/python-ides-code-editors-guide/#sublime-text).

- `TRACEBACKS.md`:

details

- Frame Object
- Line 6: "function is returns" should be "function returns".

- Call Stack
- Line 13: "then" is unnecessary here.

- How to Read a Traceback
- Line 25: "of `ValueError`" should probably be "of a `ValueError`".
- Line 36 has incorrect grammar, perhaps the first part could be "Tracebacks are organized **such that** the most recent call is last" (emphasis indicates changes).
- Line 46 and 55: It looks like `my_func()` was called on line 4, not 5.
- The examples here should probably use a simpler error (Unpacking And Multiple Assignment is near the bottom of the concept tree). The first example would be a better fit in the `ValueError` section below.

- Common Exceptions
- The headers have bold markdown when they should have code/backtick formatting instead.
- Lines 218, 249, 288, 324, and 359: "Click here for code example" should be "Click here for **a** code example."

- AssertionError
- Line 108: This should probably link to the section of the document on `assert` statements or use the reflinks present in that section.

- AttributeError
- Line 143 is a bit awkward and has inconsistent tense. Maybe it could be changed to: "For example, this error would be raised if a unit test expected a `Robot` object to have a `direction` attribute, but when it tried to access `robot.direction`, it did not exist."
- Line 158 has no space between the `#` and the comment.
- Line 162-163: The `forward()` method is not relevant here, perhaps it could be removed?
- Line 166: `Robot` should be `Robot()`.

- ImportError
- Line 214: "`Guidos Gorgeous Lasagna`" should probably be "the `Guido's Gorgeous Lasagna` exercise".
- Line 221 does not have a "(_note the message on the final line_)" or a "(_Note the last line._)".
- Line 223: The codeblock's language is "python" even though it is error output, not Python code.
- Line 241: There is no closing triple backticks and closing `` tag, which makes the next section be formatted as a code block inside the `` element.

- IndexError
- Line 245 would be clearer if "indicates the index is" was changed to "indicates **that** the index is".
- The `i` variable should probably be renamed to be more than one character long.

- KeyError
- Line 299: The comment would be clearer if "the translation" was "the translation dictionary".

- ValueError
- Line 355: "to function" should be "to a function".
- Line 362 is a bit awkward (and also `sqrt(0)` is actually valid), so perhaps it should be deleted and the next line be modified with "since negative numbers (including `-1`) are not valid values" or similar.
- Line 364: "-1" should be surrounded with backticks for consistency.

- Using the `print` function
- The comments here don't have their first letter capitalized, even though the previous ones do.
- Line 417: There is no closing triple backticks.
- Line 418: The "floor division operator" reflink no longer exists. It used to be: https://www.codingem.com/python-floor-division

- Logging
- Line 422: The "logging" reflink no longer exists. It used to be: https://docs.python.org/3/howto/logging.html
- Line 423: The logging severities should probably use backticks (or nothing) instead of apostrophes. Also, there should be an "or" between "ERROR" and "CRITICAL".
- The comments here don't have their first letter capitalized.
- Lines 438 and 456: There is a stray space in between `f"` and `num`.
- The usage of `>>>` vs `...` for empty lines differs between the first and second codeblocks.

- Python Debugger
- Line 524/636: ~~[The linked webpage](https://www.geeksforgeeks.org/python/python-debugger-python-pdb/) seems to be broken.~~ Edit: It is working now, but I think linking [the docs](https://docs.python.org/3.13/library/pdb.html) here would be better, as the document already explains most of what is in the article, and the docs would provide a point for learners to dig deeper.
- `sum` should not be used as a variable name, as it overrides the built-in function.
- Line 543: "move" should be "moves". The second sentence should be on its own line.
- Lines 540-546: This paragraph is rather long and would benefit from being split up (the common commands could be turned into a list).
- `...` is used in these code blocks even though output lines should not start with a `...`
- Lines 574-579: This paragraph is also rather long.
- Using `continue` instead of `c # continue` would probably be clearer.

- `config.json`:

- Some of the titles are in title case, while others are in sentence case. For example, "How to learn Python" vs "Problem Solving Resources".

## Shared Docs ([`exercises/shared/.docs/`](https://github.com/exercism/python/tree/main/exercises/shared/.docs))

- `help.md`:

details

- These links should be reflinks.
- Line 6: `Forums` should probably be `Forum's` or `Forums'`.
- Line 8: This link has a typo so it doesn't work. The correct link is: https://forum.exercism.org/
- Line 9: This link now [redirects here](https://www.pythondiscord.com/).
- Line 11: "Libera.chat" should be capitalized as "Libera.Chat".
- Lines 13 and 15: The [Pythontutor](https://pythontutor.com/) and [StackOverflow](https://stackoverflow.com/questions/tagged/python) links should use https.

- `representations.md`:

details

- Line 5: The first time "AST" is used, the acronym should be spelled out as "abstract syntax tree (AST)".
- Line 6: "AST tree" is redundant, it can be just "AST".
- Line 12: `if __name__ == __main__` should be `if __name__ == "__main__"`.
- Lines 26-30: The hashtags are a bit confusing, maybe they could be replaced with arrows ("-->") or a statement like "(equivalent to: )". Having spaces around the operators would also make these lines easier to read.
- Line 29: There is no space after the "-->".
- Line 32: This line should be broken up into one line per sentence. It would also be helpful to have [a link to the mentioned line](https://github.com/exercism/python-representer/blob/main/representer/normalizer.py#L153).

## Other ([`CONTRIBUTING.md`](https://github.com/exercism/python/tree/main/CONTRIBUTING.md), [`README.md`](https://github.com/exercism/python/tree/main/README.md))

TBA