[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 now redirects here.
  • Line 10/49: The "peps" link now redirects here.
  • 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 now redirects here.
  • Line 20/64: The "what is pythonic" link now redirects here.
  • 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.
  • 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."
  • Lines 32-33 and 34-35: These pairs of reflinks are the same. Is this intentional?
  • Line 38: This link now redirects here.

• 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.
  • Line 24/52: This seems to be a link to a "live" version, it is now a recorded class here.
  • Line 25/36: This link now redirects here.
  • 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 here.

• 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 now redirects here.
  • Line 20/40: The second link 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 here.

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

• TESTS.md:

  details

  • Line 3/263: This should probably link to the "stable" version of the docs, not the "latest" one.
  • Line 7/270: This link can use https: https://pythonhosted.org/pytest-cache/
  • Line 10/269: This link now redirects here (however, the stable version should probably be linked instead).
  • Line 13/278: The first link is to a very old version of pylint, it should probably link to the stable docs instead.
  • 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 pytest 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 <path_to_exercise> instead.
  • Line 204/266: This link is to an old version of the python docs. It should link to the latest supported version.
  • 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 <a name="header-name"></a> 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.
    • Line 55: The second link is to the "latest" version, it should probably link to the "stable" version instead.
    • Line 58: The last link is to the "latest" version, it should probably link to the "stable" version instead.

  • Creating a virtual environment with venv

    • Line 69 and 83: These should probably be level-four headers instead of bold text.
    • Line 98: "venvs" 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. However, I am not sure if this has the same content as the original link, and this page 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.
    • Line 109: This link now redirects here.
    • Line 113: This link now redirects here, but the stable version should probably be used instead.

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

  • 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.
    • The first link on lines 270/ and 272/ are the same but use different reflinks.
    • Line 272: The other extensions are now Pylance, Python Debugger, and Python Environments.

  • PyCharm

    • Line 283: There is a space before the period.
    • Lines 289-297: Because the collapsed <details> 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) seems to have been split into updating-a-standalone-install, updating-with-conda, and updating-with-anaconda sections.
    • Line 332: This heading (anaconda) seems to have been renamed to anaconda-base.
    • Line 333: This heading (new-conda-environment) seems to have been renamed to conda-environment.
    • Lines 337, 338, and 340: This links to an old version of the docs, it should link to the current version instead. (Link for line 338 and Link for line 340.)

  • 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 with the table of contents instead.

  • Vim

    • Line 358: The third link 404s, it has been moved to here.
    • Line 361: Here, "familiarise with" should be "familiarize yourself with".
    • Line 363: This link now redirects to here.

  • 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.
    • Lines 383-388: Some of these list items end with punctuation, while some do not.
    • Line 387: This link now redirects here.

• 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 </details> tag, which makes the next section be formatted as a code block inside the <details> 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 seems to be broken. Edit: It is working now, but I think linking the docs 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/)

• 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.
  • Line 11: "Libera.chat" should be capitalized as "Libera.Chat".
  • Lines 13 and 15: The Pythontutor and StackOverflow 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.

• tests.md:

  details

  • Line 4/85: This link is to the "latest" version of the docs, it should probably link to the "stable" version instead.
  • Line 8/88: This link can use https: https://pythonhosted.org/pytest-cache/
  • Lines 19, 24, 33, and 39: These lines should probably be level-four headings.
  • Line 47: There is no period at the end of this list item.
  • Line 75/92/93: These links are to a very old version of the pytest docs, they should probably link to the docs for the currently used version (8.4.x) 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 77/91: Similar to the previous line, the link should be https://docs.pytest.org/en/8.4.x/reference/customize.html#configuration-file-formats

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.

[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!

[BethanyG]

@lucasojeda5421 - Maybe comment on things that are still open? "persuasions" was changed to "interests" in PR4254. Please don't make irrelevant comments just to get a comment in. Thanks.