You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I believe that currently the README.md file has a significant amount of semi-outdated and unhelpful content, and needs a major refactoring. I've listed a few problems I see below, but a discussion of these issues would probably be a good idea to form an idea of the direction a refactor should go.
References to Travis CI should be updated.
References to GatorGradle should be updated or removed (for instance, I don't believe there is a need for a "Docker" section now).
The "Quickstart" section needs a complete rewrite, but should probably just point to GatorGrade and the contributing instructions, since those two actions fulfill what the majority of visitors will be looking to do.
The "Installing GatorGrader" section should be removed, and more details on this step should be added to the contributing section.
Details on installing GatorGrader through pip or pipx should be added, with a disclaimer that likely the user would want to explore GatorGrade first.
The "Testing GatorGrader" section should be moved to the contributing section.
This may be more controversial, but I believe scripts/tasks.py and the section on "Testing with Multiple Python Versions" should be removed. As a compromise, we could add information pointing to Poetry's native ability to switch the version of Python its virtual environment uses with poetry env use <python-executable-path>, since then running tests in different Python versions is as simple as pyenv local <python-version>; poetry env use $(pyenv which python); poetry run task test. I think that this, although slightly more complicated than using invoke, is simpler to understand and execute, and requires no modification to the user's installed programs. We could additionally add tasks to pyproject.toml that would facilitate switching versions or combining these commands so that the user would not need to remember each of these commands.
The "Code Linting" section should be moving to the contributing section, and perhaps combined with the information on how to run tests.
The "Automated Checks" should be condensed (I don't believe there's a need to list any of the available checks, at least -- instead just direct to gatorgrade --help or the website) and rewritten to match the more professional writing style of the rest of the document; in addition, more detail should be added on how users could create their own plugin to expose a new check.
Although unrelated to the README, I believe the website needs a rewrite and rework as well, to make surfacing checks much easier. I also believe it may be a good idea to move away from the "blog" format and instead towards a more standard "documentation website" format, such as Typer's or Pipx's, which actually both use MkDocs, a static site generator designed for software documentation.
We may also consider moving information about available checks to places like our GitHub Wiki, which is currently disabled.
The "Running GatorGrader" section should be split up into a section on "Using GatorGrader" with the content on GatorGrade (which might also be removed since it should be mentioned in the Quickstart) and how instructors normally utilize GatorGrader checks; and another section (possibly combined with the "Automated Checks" section with content on how to find the check you want or list all available checks.
In terms of ordering, I believe we should move any content that has to do with using GatorGrader (or GatorGrade) as a student first, and this content should be very short (since it is likely they intended to look up GatorGrade). Then, sectios on how to use GatorGrader as an instructor should be next, with content pointing to GatorGrade and how to extend GatorGrader with their own checks (through plugins). Finally, content on contributing to GatorGrader should be last. Information on competing tools, presentations, and the contributor list should live at the bottom of the README, after the contributing section.
Hopefully this list helps when referencing refactoring issues with the documentation for GatorGrader. It may be desirable in the future to split this list into multiple issues, especially if multiple contributors will be implementing these recommendations in multiple PRs.
The text was updated successfully, but these errors were encountered:
I believe that currently the
README.md
file has a significant amount of semi-outdated and unhelpful content, and needs a major refactoring. I've listed a few problems I see below, but a discussion of these issues would probably be a good idea to form an idea of the direction a refactor should go.scripts/tasks.py
and the section on "Testing with Multiple Python Versions" should be removed. As a compromise, we could add information pointing to Poetry's native ability to switch the version of Python its virtual environment uses withpoetry env use <python-executable-path>
, since then running tests in different Python versions is as simple aspyenv local <python-version>; poetry env use $(pyenv which python); poetry run task test
. I think that this, although slightly more complicated than usinginvoke
, is simpler to understand and execute, and requires no modification to the user's installed programs. We could additionally add tasks topyproject.toml
that would facilitate switching versions or combining these commands so that the user would not need to remember each of these commands.gatorgrade --help
or the website) and rewritten to match the more professional writing style of the rest of the document; in addition, more detail should be added on how users could create their own plugin to expose a new check.Hopefully this list helps when referencing refactoring issues with the documentation for GatorGrader. It may be desirable in the future to split this list into multiple issues, especially if multiple contributors will be implementing these recommendations in multiple PRs.
The text was updated successfully, but these errors were encountered: