[REVIEW]: The Riffomonas Reproducible Research Tutorial Series about jose-reviews HOT 43 CLOSED

Actually, we've been having a conversation in another review that tends to leaving the Statement of Need in the paper only. That is, not requiring it in the documentation.

from jose-reviews.

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks. @jhollist it looks like you're currently assigned as the reviewer for this paper 🎉.

⭐ Important ⭐

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:

1. Set yourself as 'Not watching' https://github.com/openjournals/jose-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

👋 @jhollist — here's where the review happens! Feel free to ask any questions, tagging the author or handling editor, as needed. You can also open issues on the repository of the submission.

from jose-reviews.

@tracykteal I'm hoping you can secure a second reviewer for this submission. Thanks!

from jose-reviews.

@labarba and @tracykteal, I have a couple of questions about the review checklist.

1. I assume the "statement of need" in Documentation and JOSE Paper are the same?
2. How should the Documentation be presented in the submission? I am still going through the review but am pretty sure all of the required things will be there. Didn't know if you were also looking for a more concise doc (i.e. a README) that had all of this in it.

Hope to finish this up today, but if not it'll be week after next (on vacation next week).

from jose-reviews.

It looks like the submitted paper reproduces verbatim the contents of the repository's README. Hmm...

from jose-reviews.

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 goal is that someone reading the JOSE paper has enough information to decide if they'd be interested in adoping the learnig module or software.

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.

from jose-reviews.

Looking now at the Introduction tutorial, I find a statement that succinctly says what this is:

this is a series of tutorials on improving the reproducibility of data analysis for those doing microbial ecology research. [...] the data set that we're going to be working with [...] is from the human microbiome research.

I wish this to-the-point statement appeared at the top of the paper!

from jose-reviews.

Thanks for the guidance! I was leaning in the same direction on the README. Will include in my review as well.

from jose-reviews.

@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:

Authors make the case for their submission's contribution in the paper, under the heading "Statement of Need."

@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.

from jose-reviews.

Didn't get finished on review today. Will finish up week of July 16th.

from jose-reviews.

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.

Should I go ahead and fix things up now as the reviews come in or wait until @jhollist (and @tracykteal?) has had a chance to go through it?

from jose-reviews.

If you're going to re-structure the writing in the paper and README, it's probably a good idea to start now, so when the reviewer and managing editor come back to it, they can comment on your updated version.

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

FWIW, I've updated the README and paper.md files to reflect @labarba's comments

from jose-reviews.

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.

from jose-reviews.

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.

from jose-reviews.

Was happy to do this review, @tracykteal and happy to be asked so early in the life of JOSE. I have some follow up on breaking the tutorials up but will put that over on riffomonas/reproducible_research#12

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

Thanks again for the review @jhollist and @tracykteal - I have addressed the comments over at riffomonas/reproducible_research as separate issues. I'm happy to follow up on any of the comments if you have further suggestions or comments.

from jose-reviews.

@jhollist and @tracykteal — Is this submission ready for acceptance?

from jose-reviews.

Issues have been resolved. @pschloss will create version 1.0 and then we'll get it in for acceptance.

from jose-reviews.

I concur! The issues have been resolved. I look forward to recommending this material and think it will be a great first pub for JOSE!

from jose-reviews.

Everything should be all set - let me know what else you need me to do at this point.

Thanks!

from jose-reviews.

You're all set! We'll get it published!

from jose-reviews.

Thank you so much for your submission. We're very excited to have this in JOSE.

from jose-reviews.

Sorry, one more thing. Can you create an archive (on Zenodo, figshare, or other) and post the archive DOI here. Then we link to that DOI for the publication.

from jose-reviews.

Wonderful - here you go:
https://doi.org/10.5281/zenodo.1404230

from jose-reviews.

@whedon set 10.5281/zenodo.1404230 as archive

from jose-reviews.

OK. 10.5281/zenodo.1404230 is the archive.

from jose-reviews.

@jhollist Not all review-checklist items are checked, but you commented above that you are satisfied with the revision. Can you complete the checklist?

from jose-reviews.

On vacation now with very flaky connection! Will finish this up on my return this Saturday.

from jose-reviews.

@jhollist had conveyed in the project repository that those items have been addressed, so I updated the checklist. @labarba this should be officially accepted and published. Thanks!

from jose-reviews.

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://jose.theoj.org/papers/10.21105/jose.00013/status.svg)](https://doi.org/10.21105/jose.00013)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/jose.00013">
  <img src="https://jose.theoj.org/papers/10.21105/jose.00013/status.svg" alt="DOI badge" >
</a>

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:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://jose.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3ODA=

from jose-reviews.

Yay! @pschloss —Your JOSE paper is now published and you can add the lovely green badge to your repo!

Tremendous thanks to @jhollist for reviewing and @tracykteal for handling the submission. Your volunteer efforts are helping us trail-blaze in new-wave publishing 🎉

from jose-reviews.

Wonderful - thanks everyone!

from jose-reviews.

Congratulations! And thanks to @tracykteal for taking care of the checklist for me.

Enjoyed reviewing this one.

from jose-reviews.