Skip to content

Review Documentation

Jump to bottom
Jonathan Graves edited this page Jul 24, 2023 · 1 revision

Thanks for helping out with COMET! We can always use more people to help us review documents and make improvements.

  • You can find the List of Reviews at this link. These are documents that are ready for review. Follow the instructions when they are complete.

Purpose of a Review

The goal of a document review is to mimic what a classroom experience would be like for a user, and identify any issues. Issues typically fall into four categories:

  • Category 1 - Bugs: some code does not produce the correct result, or does not run at all. All reviewable software should be able to run on UBC's JupyterOpen environments without any package installation.
  • Category 2 - Error: there is a mistake in some of the content; the document says something which is not true or is confusing enough to be ambiguous.
  • Category 3 - Typos or Formatting: there is a spelling or grammar mistake, or the formatting of something (including code) is messed up.
  • Category 4 - Stylistic or Clarity: there is something unclear or the style of something is awkward.

Category 1 and 2 errors are critical and will be fixed as soon as possible. Category 3 and 4 errors are non-critical, and will be fixed as part of routine improvements.

The job of a reviewer is to test documents and identify and log issues.

Review Process

  1. Start by checking the List of Reviews, and choose one which has not been completed.
  2. Before you start, check the Issues page to make sure it hasn't been accidentally started. If it has, add a comment to the issue to remind the admins to update the list, and choose another issue.
  3. Otherwise, make a new issue for your review, and find the notebook on COMET. All new issues should have:
  • A title which is the name of the module on COMET
  • A label which is category of the module on COMET
  • A label which is the status (initially, choose in progress)
  • The first parts of the body of the issue should be:
    • The date on COMET of the last update for the module
    • The URL to the module on COMET
  1. Then, assign the issue to yourself and get started!
  2. Launch the module on JupyterOpen, and then work through it. As you spot errors, add them to the body of your issue. Update the label of your issue with the highest category error, to track the seriousness.
  3. Try to be descriptive about the error: use bullet points, and give the exact location and issue. If it's a coding issue, show the error or point of failure.
  4. When you have completed the module on JupyterOpen, check the COMET webpage for any additional display issues.
  5. Finally, check the issue label from in progress for ready for review. Assign the issue to the review lead you were assigned.

Keep an eye on your issues after you have completed them. The review leads may have clarifications or questions if things are unclear.

  • If you can, feel free to make suggestions in the comments for the issue for how to fix errors. Or you are welcome to make changes - but do so to the .qmd files if present, and submit a pull request.
Clone this wiki locally