FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

[General Docs] Audit/Cleanup of Track General/Shared Docs · Issue #4237 · exercism/python · GitHub

  1. exercism
  2. python

Repository navigation

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

Open
Open
[General Docs] Audit/Cleanup of Track General/Shared Docs#4237
Assignees

Description

Yrahcaz7
opened on Jun 5, 2026

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

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

  • 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

  • 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

    • 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

    • 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

    • 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

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

Other

  • CONTRIBUTING.md:

    • TBA

  • README.md:

    details
    • Overall: Some lines have trailing spaces (see MD009).
    • Line 1: This <br> is unnecessary.
    • Line 4: The enclosing <p> element is unnecessary (its vertical-align="middle" actually does nothing here; the header only appears vertically centered because of the image's specific dimensions).
    • Lines 6-9, 21, 23, 71, 93, and 99 have inline links that should be converted to reflinks.
    • Line 7: "Exercism_II" is not good alt text. Since the badge's label is not dynamic, it should be used instead: "Python 3.13 Powered | Exercism-Built"
    • Line 8: "Exercism_III" is not good alt text. Since the badge's label is not dynamic, it should be used instead: "Contributions PAUSED"
    • Lines 15-26: The enclosing <table> and <tr> elements do nothing here, as <tbody> and <td> are missing (GitHub's HTML parsing is a lot stricter than typical parsers). The tags should be removed, as fixing the table breaks the styling.
    • Lines 30, 41, 53, 63, 70, and 78: There are unnecessary &nbsps here.
    • Line 32: Two <br> elements make an an excessive amount of space here, one <br> is likely sufficient.
    • Line 34: This should be exercism/python, not exercism/Python.
    • Lines 37 and 39: The 🌟 &nbsp;&nbsp; should be replaced with markdown list syntax: - .
    • Line 43: "config.json" should be surrounded with backticks.
    • Line 43: The mention of the exercises directory should use a relative link to link to the directory.
    • Lines 48-50: The enclosing <span> here is unnecessary.
    • Lines 51-58: The enclosing <span> here is unnecessary (the align property does not exist on span elements, so it does nothing here).
    • Lines 79 and 80: The indentation created by the leading &nbsps seems unnecessary here.
    • Line 80: "version in contributing on exercism.org" is very confusing, was this supposed to mean "contributing docs on exercism.org"?
    • Line 93: These sentences should be split up into their own lines.
    • Line 118: This link is now invalid because the file was changed to a folder with a README.
    • Line 124: This link does not go to the right header anymore, as it was renamed to zero-clause-bsd-license-for-code-in-the-python-documentation.

Activity

  1. github-actions commented on Jun 5, 2026

    github-actionsBot
    on Jun 5, 2026 – with GitHub Actions · Hidden as resolved
  2. github-actions
    closed this as completedon Jun 5, 2026

  3. Yrahcaz7 commented on Jun 20, 2026

    Yrahcaz7
    on Jun 20, 2026
    ContributorAuthor

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

  4. BethanyG
    reopened this on Jun 20, 2026
  5. BethanyG
    self-assigned this
    on Jun 20, 2026

  6. Lucifer-ipynb2 commented on Jul 21, 2026

    Lucifer-ipynb2
    on Jul 21, 2026

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

  7. BethanyG commented on Jul 21, 2026

    BethanyG
    on Jul 21, 2026
    Member

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

  8. BethanyG commented on Jul 22, 2026

    BethanyG
    on Jul 22, 2026
    Member

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

  9. Yrahcaz7 commented on Aug 1, 2026

    Yrahcaz7
    on Aug 1, 2026
    ContributorAuthor

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

  10. BethanyG commented on Aug 1, 2026

    BethanyG
    on Aug 1, 2026
    Member

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

  11. exercism
    deleted a comment from on Aug 7, 2026

  12. BethanyG commented on Aug 11, 2026

    BethanyG
    on Aug 11, 2026
    Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

    Back | FazBrowse Home | New Git URL