Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor README.md #246

Open
Michionlion opened this issue Oct 17, 2022 · 0 comments
Open

Refactor README.md #246

Michionlion opened this issue Oct 17, 2022 · 0 comments

Comments

@Michionlion
Copy link
Member

Michionlion commented Oct 17, 2022

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.

  1. References to Travis CI should be updated.
  2. References to GatorGradle should be updated or removed (for instance, I don't believe there is a need for a "Docker" section now).
  3. 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.
  4. The "Installing GatorGrader" section should be removed, and more details on this step should be added to the contributing section.
  5. Details on installing GatorGrader through pip or pipx should be added, with a disclaimer that likely the user would want to explore GatorGrade first.
  6. The "Testing GatorGrader" section should be moved to the contributing section.
  7. 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.
  8. The "Code Linting" section should be moving to the contributing section, and perhaps combined with the information on how to run tests.
  9. 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.
  10. 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.
  11. We may also consider moving information about available checks to places like our GitHub Wiki, which is currently disabled.
  12. 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.
  13. 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.

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

No branches or pull requests

1 participant