JOSS Paper review 2

[ArneTillmann]

Dear @EssamWisam,

first, thank you for submitting this great paper. I think you have already done a very good job at providing the community with this useful package.

I have only stumbled about some minor issues that I think will be quick fixes:

1. Look at the missing and incorrect references that the editorial bot points out.
2. In the section "Imbalance.jl Design Principles" you list all the "shoulds" and then say that you met these "shoulds". This is redundant and slows the reading flow. I like that you list the implemented techniques and Interface Support. Wouldn't they fit equally well in the section "Imbalance.jl"? Some of the "principles" are already mentioned and then you would avoid the confusion what are the four principles mentioned in the issue JOSS paper minor issues #85.
3. The subsection "User Experience" is not necessary in my point of view as those are basic design principles for software dev.
4. On a superficial level, instead of mentioning all the principles that are already included, you could rather have small section on future work or suggestions for contribution (not necessary).
5. (Line 118 could be regarded as a widow, tho don't worry too much about those.)

[EssamWisam]

Thank you so much for the positive words and your valuable time.

I will consider fixing (1), (5). I see how (4) may make sense but I as well feel that the purpose of a future work section would be orthogonal to this. I agree that it could be worth adding a future work section eitherway.

As for (3), it's there just for completeness and because the specific user experience principles mentioned therein can be viewed to be on average not principles that software developers tend to emphasize. Could we agree that it doesn't hurt to keep it?

As for (2):

In the section "Imbalance.jl Design Principles" you list all the "shoulds" and then say that you met these "shoulds". This is redundant and slows the reading flow.

I seem but if I take off that we meet such "shoulds", one may assume that they are not met as the section is about the design principles.

I like that you list the implemented techniques and Interface Support. Wouldn't they fit equally well in the section "Imbalance.jl"? Some of the "principles" are already mentioned and then you would avoid the confusion what are the four principles mentioned in the issue #85.

In my view, not exactly equally as it could be too much information to comprehend if I add them all there (specificially interfaces) compared to having these details in an organized seperate section. The "Imbalance.jl" section is meant to be a swift introduction. You're right that there may be some little redundancy in this but wouldn't you agree that the vast majority of the principles are facts not mentioned earlier so it could be okay? I also proposed a specific workaround for #85 in the issue.

Thank you for the valuable thoughts.

[ArneTillmann]

Regarding (2) You could write something along the lines like, the implemented technology feature are... [the list of bulletpoints].

The "Imbalance.jl" section is meant to be a swift introduction.

Have a look at other JOSS paper. The summary is meant to provide a brief introduction. When you present your package, the reader wants to have all functionality at first glance. At least restructure the paper paper that you include the section "principles" in the section "Imbalance.jl" as a subsection.

As of (3), I disagree, because it distracts from the important information.

Regarding (4), I would only include it in the docs and only, if you have such a list already.

[EssamWisam]

Regarding (2) You could write something along the lines like, the implemented technology feature are... [the list of bulletpoints].

This is to say it could be better to call the section "Package Features" instead of "Design Principles" right? I do have a preference towards the latter if you also find that sensible.

Have a look at other JOSS paper. The summary is meant to provide a brief introduction. When you present your package, the reader wants to have all functionality at first glance. At least restructure the paper...

I likely mainly considered the JOSS documentation which says that the summary should explain high-level functionality and purpose of software. Notice that the Imbalance.jl section is inside the Summary section in the paper.

I can try make the Imbalance.jl section be a main section and have the design principles come under it. Would this align with your recommendation?

Regarding (4), I would only include it in the docs and only, if you have such a list already.

I believe it's already in the docs. Particularly in the contribution page. So you're saying that it wouldn't make sense to add a "Future Work" section to the paper, eh?

As of (3), I disagree, because it distracts from the important information.

Wouldn't you agree that it shouldn't have such negative effect especially because it's the last subsection in the whole paper? Or would you agree that taking it off would imply that readers of the paper will have to figure out that these user-related features exist on their own?

Thank you again for your valuable comments.

[jbytecode]

Due to the JOSS submission

openjournals/joss-reviews#6310

[ArneTillmann]

I can try make the Imbalance.jl section be a main section and have the design principles come under it. Would this align with your recommendation?

Sounds good to me

This is to say it could be better to call the section "Package Features" instead of "Design Principles" right? I do have a preference towards the latter if you also find that sensible.

No no, I was only trying to rephrase the paragraph to avoid the redundancy. I don't mind it that much and think the above restructuring is more important.

I believe it's already in the docs. Particularly in the contribution page. So you're saying that it wouldn't make sense to add a "Future Work" section to the paper, eh?

Found it. Sorry for the confusion.

Wouldn't you agree that it shouldn't have such negative effect especially because it's the last subsection in the whole paper? Or would you agree that taking it off would imply that readers of the paper will have to figure out that these user-related features exist on their own?

I'll leave the decision to you, whether you want to keep it or not.

[EssamWisam]

@ArneTillmann Thank you for your valuable comments. I have updated the paper accordingly. Could you check it and let me know if it meets your expectations now.

[EssamWisam]

Of course, whenever you get the chance.