JoSS Review: Request for Proofreader

[vsoch]

hey @nuest and @kyleniemeyer - I started reviewing your manuscript, but I keep hitting spelling mistakes, and weird sentences - could you please find someone to proofread the draft that can help here? I'm happy to correct small issues, but I'm spending a huge amount of time with just grammar, and I'd like to ask that you find someone to read it over first, and I'll start my review after. Thank you!

[nuest]

Hej @vsoch - I am not a native speaker, but have not had this feedback before. Thank you for pointing this out so directly, I'll organise a proofreading.

[vsoch]

Thanks! Here is what I had edited so far (a few paragraphs in). You can likely ignore the changes of s -> z, but we should double check that JoSS doesn't favor one over the other.

ContainerIt Review

Manuscript

First I will review general comments for the manuscript

• I don't know if JoSS has a set language standard, but in case it's US, "standardised" should be "standardized"

Running an analysis in a container increases trust in a workflow, as it can emulate an execution of the code independent from the author’s computer

I know what you are trying to say, but I don't think "trust" is the correct word. No container can really be trusted, but rather, maybe "Running an analysis in a container increases reliability of a workflow?"

as it can emulate an execution of the code independent from the author’s computer.

Emulate suggests that it's some sort of emulation. I think what you mean to say is something like "as it can execute code independently from the author's computer" or "as it can execute packaged code without relying on dependencies from the author's computer."

However, especially domain scientists with limited programming experience struggle with the complexity of capturing their computational environment in containers. containerit opens up containerisation’s advantages to a much larger user base by assisting researchers in packag- ing workflows based on R

I think you mean to have a comma after "environment in containers," and the sentence reads a little funny. I would also rephrase this to be something like:

Since domain scientists with limited programming experience struggle with the complexity of capturing their computational environment in containers, a tool like containerit can help.

Containerisation took off during the last years

This reads funny too. Maybe say "Containerization has recently taken off, or Containerization has taken off"

I don't think you need "during the last years," because you've referenced many recent papers that give the reader a sense of the time period.

The most widely used containerisation software is Docker with the core building blocks image, which is (a) built from the instructions in a recipee called Dockerfile, (b) executed as a container using a container runtime, and (c) moved between systems as files (image tarballs) or based on an image registry (see Docker: Get Started).

This sentence also reads kind of funny, and note the typo that recipee only has one "e" at the end.

I think you want something like:

The most widely used containerisation software is Docker, which builds container images from the instructions in a recipe called a Dockerfile, and assembles layers at runtime to create a container.

I don't think you need to add details about moving between systems and registries. If you want to keep that, the part of the sentence that needs to be reworked is

The most widely used containerisation software is Docker with the core building blocks image

Recipe again

The duality between recipee

recipe

review and to some extend preservation

extent

[kyleniemeyer]

Just jumping in here due to the JOSS connection—I think the specific suggestions @vsoch made look good and will improve readability. We do not really have a preference of s vs. z, other than consistency. (Though I am personally a stickler for Oxford commas and will fix those when they are missing...)

But, after reading through the paper (albeit fairly quickly), I didn't run into more than a few actual typos or errors—certainly not enough to impede my understanding. Most of the above suggestions are more about subtler word and phrasing choices that impede readability a bit. Good suggestions, yes, and I appreciate the time @vsoch put into providing them! But not really critical errors, in my opinion.

(Though I admit that I also generally struggle to get through something and focus on the content when I encounter issues like this myself 😄)

Also, as some friendly feedback, I think we should avoid any comments or questions about "native English" speakers/writers—if there are major issues with grammar, typos, or technical writing, then we can certainly point those out, but whether English is someone's first language does not have much to do with quality of technical writing, or ability to fix such.

[kyleniemeyer]

@nuest I made a few minor fixes (commas after "e.g.", ensuring semicolons between grouped references) here: https://github.com/o2r-project/containerit/pull/154

[vsoch]

My apologies, in many journals I've submitted to / reviewed for there are explicit questions / boxes to check about if there are a large number of issues related to grammar. For example, the following sentences don't have correct structure:

• The most widely used containerisation software is Docker with the core building blocks image,
• Containerisation took off during the last years
• However, especially domain scientists with limited programming experience struggle with the complexity of capturing their computational environment in containers. containerit opens

I wanted to suggest having the draft proofread before review. I'm okay with small grammar issues (commas and spelling mistakes) but as a reviewer my main focus should be the content and then the software. I don't think it should be my responsibility to fix grammar in the draft, because that takes a really long time and it's a huge investment and extra burden. I started to do it, but stopped when I realized it's not what I should be reviewing. Again, I apologize if I offended someone with my request, I definitely didn't mean that.

[vsoch]

If you think this should be part of my responsibility, then perhaps I'm not a good reviewer for this paper.

[kyleniemeyer]

Sorry, I think I tried to cram too many things into my message above and the end result was not clear.

I agree it isn't your (or any reviewer's) responsibility to edit or correct language in a submission. Suggesting the authors proofread / edit the paper to improve readability is absolutely appropriate for a reviewer, especially paired with a few examples as you did.

I appreciate the effort you did take in suggesting corrections, and I agree there are some additional places where things can be improved. Requesting another round of internal edits/proofreading is also perfectly fine, especially if you found the paper difficult to read. I personally didn't find the issues got in the way too much, but that was just my opinion—your opinion on this, especially as someone working closer to the application area, is very valuable!

[vsoch]

Apologies again for not putting it very well - I edited the original comment so it's removed and we don't have to continually be offended by my lack of social skills :) I'm looking forward to reading the updated draft, let me know when to take a look!

[nuest]

Thank both of you for the helpful comments. Based on your feedback and feedback provided by a native speaker from my university's writing support service (a stupid oversight on my side not to engage with them earlier) I have committed a revised manuscript.

Re. BE/AE: I use British English throughout the document and hope nothing has slipped by so it is consistent.

Here are the changes: https://github.com/o2r-project/containerit/commit/52b624dad4d880967c061ebe257322b292806ffd