Skip to main content

Tool Report Cards

Riverscapes software are accompanied by report cards that capture the status of the tool/script/model/code. The goal is to provide a quick reference for consumers of the software to gain an understanding of the tool, how they can use it and set expectations around its quality. The report cards provide:

  • A summary assessment of tool-grade (e.g. research-grade) and Riverscapes Compliance or Pending Riverscapes Compliance.
  • Evaluation of:
    • Tool Interface(s)
    • Scale
    • Languages & Dependencies
    • Vetting in Peer-Reviewed Literature
    • Source Code Documentation
    • Open Source
    • Tool & Source Code Citeable
    • User Documentation
    • Easy User Interface
    • Scalability
    • Produces Riverscapes Project
  • F-A-I-R Assessment of
    • the metadata the tool produces
    • the data the tool produces
    • the tool itself
  • Tool Output Utility

Explanation of Report Cards

The video below is an excerpt from a longer talk, but positioned where the concept of report cards for the RC are explained:

Requesting a Review

If you are the developer of a tool and you would like a review, please fill out this form.

For Reviewers

Reviewers should follow the guidelines on here.

Report Card Instructions

See the blank Tool Report Card Template for a preview.

A copy of the markdown template can be downloaded or copied here

Typically, the Technical Review Committee will be filling out this markdown and these instructions are for

Step 1 - Rename the file

We recommend putting report cards (allows for multple versions) in a About\Status\ subfolder located in the root of your website folder (e.g. Docs). Reviewers should provide a working version of the markdown to the GitHub source code as a review branch. Copy the template and then rename it from Tool_ReportCard_0-0-00.md to what ever version you are publishing (this should match your GitHub release). For example, if you are publishing a report card on version 1.2.1, it would become Tool_ReportCard_1-2-01.md.

Step 2 - Complete Review

The review needs to updated to fill out the Value, Evaluation and Comment columns of each of the table. Multiple members of the Techncial Review Committee should indepently assess and then a lead reviewer will provide a rough draft to the others. Members should proof-read the review for typos and accuracy.

Step 3 - Submit Pull Request to Developer

Once the review is completed, the lead reviewer should submit a pull-request, and assign the developer requesting the review, to review and approve the pull-request.