Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
[REVIEW]: The Riffomonas Reproducible Research Tutorial Series #13
Submitting author: @pschloss (Patrick D Schloss)
Status badge code:
Reviewers and authors:
Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)
Reviewer instructions & questions
@jhollist , please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:
Review checklist for @jhollist
Conflict of interest
Code of Conduct
Pedagogy / Instructional design
referenced this issue
Jun 11, 2018
If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/jose-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews
To fix this do the following two things:
For a list of things I can do to help you, just type:
Hope to finish this up today, but if not it'll be week after next (on vacation next week).
I find it unsatisfying that the paper and the README have the same contents. These documents have different goals., in my opinion
About the paper, the Author Guide says:
The paper is a form of "scholarly advertisement" of the learning module. Readers want to know who the target audience, the design behind the learning module, how it could be used by another instructor or by an independent learner, how it has already been used in the classroom or elsewhere, and of course a description of the contents.
The README is the entry point to the repository, and it might be too lengthy to include all of the above. It should have installation instructions, list of dependencies, maybe statements about the license and how to contribute, and include an index of the lessons, with links.
Looking now at the Introduction tutorial, I find a statement that succinctly says what this is:
I wish this to-the-point statement appeared at the top of the paper!
@pschloss : I would like to see the bullet lists on slides 5 & 6 of the Introduction lesson, just like that, on the paper. It gives the reader an immediate picture of the contents of the module!
Also, in the Statement of Need (in the paper), you give general statements about reproducibility, about the field of microbiome research, and so on, and only in the final sentence refer to this tutorial. What we really want in this section is a statement about how this tutorial satisfies a particular need, and perhaps how it differs (or is similar) to other tutorials on the subject.
From the Author Guide:
@tracykteal : I'm stepping in here, in this review that you're editing, because with the first handful of papers in JOSE we are in fact defining our genre.
Thanks for the feedback and my apologies for missing the desired distinction between the paper and the README. Part of the "problem" as you all have identified in the thread here is that it's early days for the journal and I didn't have a lot to go off of for examples.
All, done with my review (better late than never and apologies for taking so long). I have updated the checklist above and am providing a more detailed review in the target repo: riffomonas/reproducible_research#12
Any questions about the review or if you need me to place items here as opposed to the Riffomonas repo, let me know.
Thanks for asking me to do the review.
Thanks so much @jhollist for doing this thorough review and the more detailed review notes. Just reading through your comments so I can come back and provide some recommendations.
JOSE reviews are discussions rather than a yes/no type of decision. Since we are just developing the pedagogy / instructional design section, that in particular is more of a discussion about suggestions. @jhollist made some nice suggestions, but @pschloss you don't necessarily have to implement all of the recommendations. It would be great to continue discussion on that issue that Jeff started.
One major point Jeff mentioned was that some of the sections had potentially a bit too much content. Given that the slide decks have accompanying video, I can see that it would be difficult to make that change however.
One point for the checklist is the Version. @pschloss it looks like there hasn't been a release yet. Before publication you can do a release and add the version.
If you would like to include a link to your paper from your README use the following code snippets:
This is how it will look in your documentation:
We need your help!
Journal of Open Source Education is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following: