Usability Testing and Scientific Verification Steps

[cansavvy]

Here's an step by step explanation of how I think these steps should happen. I'm envisioning @danieljgroso to be the lead on this effort.

Goals

Basically the goal is to make sure that the code and vignette coming through is overall useful for future Berger labmates (and other people who want to use this pipeline. To this end we want to make sure the vignette and code is:

1. Clear - Understandable and able to be run and followed
2. Valid - Scientifically follows the goals and principles laid out by the original code in https://github.com/FredHutch/GI_mapping

Steps

Here's what I'm picturing for the steps you'd follow to do this (happy to talk about this at our meeting later)

1. After a change has been merged to main (@kweav or I will tag you on Slack). Fetch the latest main branch on your local computer.
2. Create a new branch.
3. Click on the gimap.Rproj to open the project with the appropriate working directory set.
4. In your R console of choice run devtools::load_all() -- this is the equivalent of running library() but for a tool that is still in development in your current directory.
5. Open up the file vignettes/getting-started.Rmd.
6. Review and run each step of this vignette evaluating for 1. clarity and 2. scientific validity as you go along.
7. Add any notes about the science or clarify instructions as you see fit. This includes:
   • Add any additional resources as links that may aid one of your future lab mates in understanding what's going on.
   • Point out how to interpret any plots or output -- what are indicators that we may need to look out for that something with the data may be "off"?
   • Help us make our writing about the code more clear -- is there anything we said that's too jargony or needs better explanation?
8. After you've gone through the latest of the code there and added all the notes you think would help, push the latest version of the vignette and open up a pull request.
9. In the pull request you open please list your overall review of the changes and what you think could be changed or altered. If you have overall questions about what we've done, then describe there
10. When you are ready for a review of your work, tag me, @cansavvy and I'll look it over!

If at any time you are not sure where to start or are not sure if something is scientifically valid, message the channel in Slack (or talk to your Berger labmates) and we can help you figure it out!

Secondly, if we feel this process isn't working for you at any point, message me and we can try to figure it out or schedule time to walk through it together.

[danieljgroso]

Add any notes about the science or clarify instructions as you see fit. This includes:

Here, would you prefer that I add comments directly to the code? or would any notes for clarification just be listed in the pull request description?

[cansavvy]

TODO: is a fine way to make notes as well. See this article: https://medium.com/imdoneio/the-imdone-pitch-feedback-welcome-386430accf01