JOSS paper structure and grammar

[brynpickering]

The content of the paper covers what I see to be the content of the software package, but it reads strangely as a publication. I would recommend restructuring and proof reading it for spelling/grammar. Some more specific comments are:

1. The summary starts with the reason for initial development ('We developed ... with a primary intent ...'). To ensure readers understand why they should use the software, could you start it with what the software is for now, rather what it was initially developed for? E.g. 'The Multiscale Solar Water Heating (MSWH) is a package to simulate individual and community scale solar water heating projects and compare them with the performance of conventional natural gas tank water heaters.'. Notice that the content is the same, but the framing is different.

2. The summary then follows as a series of sometimes disconnected statements, rather than a flow of text. The bullet points work to describe the component parts, so I wouldn't remove those, but they should be accompanied by a more coherent text. Particularly, you should avoid switching between the purpose of the software and the implementation details. I would start with a paragraph on the purpose, i.e. for comparing systems in CA and (potentially) beyond, including simple examples of things that could be compared. At this point you can briefly mention why it was initially developed to give context to e.g. the CA geographic focus. This can then be followed by the user-facing implementation, describing the existence of functional examples, a GUI (worth giving more detail on this, since it is quite a nice part of it all), and the relatively few inputs required by a user to do it all. Then you can finish on why this software is not only accessible to a user, but also functionally robust, i.e. the underlying model and its components.

3. The statement of need is more focussed on why you needed it to begin with, rather than why anybody else might need it now. As a result it is only in the last sentence where you make any mention of a target audience other than your past selves.

4. Articles tend to be missing or misused. 'MSWH' -> 'the MSWH' (and you should choose between 'the MSWH package' and 'the MSWH software'), 'SAM tool' -> 'the SAM tool', 'in order to capture sufficient level...' -> 'in order to capture a sufficient level...', 'a primary intent' -> 'the primary intent', 'very similar to model developed' -> 'very similar to the model developed', 'The application of the models' -> 'An application of the model'?

5. There are some very long sentences, which make it difficult to read. For example: 'The project that prompted the development of this software, described in @Coughlin:2020, that is at the moment of this writing in press, was enquiring whether there are any economic benefits in grouping households to be served by a single solar water heating installation, in comparison to single household solar water heating installations on the state of California level.' is a 58 word sentence.

6. Links in the PDF should point to a tagged version of the software, rather than the current master. That way, as and when the software changes, those links don't become stale. You may prefer to do this as a final step, when you have released your most up-to-date version following paper acceptance.

Note: this issue comes to you as part of my wider JOSS review

[milicag]

@brynpickering Thanks, I will address this to my best capabilities.

1 - This is as the code was a deliverable for the project. Also I though it was more honest to state that fact, but if you are so confident that this is well rounded as a standalone software then I am happy to follow your guidance.

2 - I will do my best to follow this! It's the way my brain functions.

3 - Same as 2.

4 - Typical for folks who don't have articles in their mother tongue.

5 - I developed a liking to long sentences, although I can make sure to shorten that one.

6 - Great idea.

[milicag]

• [x] 1
• [x] 2 - Notes: A lot of the detail on components and models will be available once the report is published. They keep telling us this should happen any time now, so I would stick to referencing the report for such detail. I added some examples on future use to the statement of need section and restructured the text a bit. There were a few sentences that indeed did not make much sense any more.
• [x] 3
• [x] 4 - Notes: based on this resource I will keep SAM rather than the SAM. Also a primary intent as this is the first time I introduce primary intent, otherwise you could ask which primary intent. For similar reasons very similar to the model developed should also be an a I think, as we are otherwise saying that something is defined which we define in the rest of the sentence, though I did change it to your liking as I can convince myself to believe in short timescale perturbations.
• [x] 5
• [x] 6 - Add to issue #16.

[brynpickering]

The changes look good to me. Just some minor comments:

1. I certainly hope it is valuable as a stand-alone software. A lot of time and effort has gone into it, so it would be great if others use and extend this software.

2. The structure looks good to me; it read much more fluidly. The only bit I would look to update is the sentences starting Now we would like to address some of the characteristics, which still read a bit strangely.

3. On the SAM question, since you're referring to the tool and SAM is something of a noun adjunct (grammar buffs might correct me), it should be the SAM tool. If referring to just SAM then the the is indeed redundant. Happy to concede on primary. I guess I see it as a superlative, so there can only be one primary thing (and therefore = the primary ...), but that's probably a questionable viewpoint ;). Also happy with either article for model, it just had neither before.

4. Long sentences are a dangerous thing to become addicted to, best to wean yourself off them sooner rather than later!

I have seen a number of minor grammatical errors creep back into the text on this re-write. Are you able to have a native English speaker read through it and make necessary edits?

[milicag]

@rhosbach Would you have time to take a quick look at this version of the paper and see if there is anything that looks grammatically incorrect from your point of view?

[milicag]

@brynpickering Are there any other action items on this or may I merge after Robert takes a look? Would you like to read it again after Robert finishes or should that be considered finalized at that point?

Many thanks!

[brynpickering]

Worth merging it in after that point so we can get a PDF generated on the main JOSS review page.

[milicag]

@brynpickering: I am hoping that Robert will be willing and have time to take a look. The team of co-authors has reviewed the paper prior to the submission. I live for many years now in an English speaking country. I do not understand what is wrong with starting a sentence with: Now we would like to address some of the characteristics. The international scientific community should respect the conventions put forth by diversity and inclusion.

[milicag]

@sjpfenninger, just as FYI.

Robert will be able to take a look on Monday.

[brynpickering]

@milicag my comment on having a native English speaker go through it was due to your own admission that certain mistakes could be attributed to English not being your mother tongue. Except for a few slip-ups, your English is very good. It would just be good to iron out those few issues before publication.

The paper structure and writing style is independent of the grammar or language profiency. In this case, having sentences that are to the point will improve clarity. Although not particularly academic, there's nothing wrong with a sentence starting Now we would like to address some of the characteristics..., it's just redundant. It would be enough to simply state "The MSWH software connects simplified, fast-performing component models to describe two preconfigured solar water heating systems. These systems and their component models are: ...".

"quality of writing" is one of the JOSS paper checkpoints, and I had hoped to point to an area that would benefit from revisiting. Everyone wins when papers are as readable as possible! Saying that, I won't push this further, if you and your co-authors would prefer not to spend more time on it.

[milicag]

@brynpickering If you allow me to have a say in this, to me saying "The MSWH software connects" lacks accuracy and is from an academic perspective misleading, as we have connected the components in systems manually. The tools that do such connections automatically are hard to build. Would it be fine with you if I rephrase it in some other way?

[milicag]

@brynpickering I am certainly happy to work towards meeting the required quality of writing!

[brynpickering]

@brynpickering If you allow me to have a say in this, to me saying "The MSWH software connects" lacks accuracy and is from an academic perspective misleading, as we have connected the components in systems manually. The tools that do such connections automatically are hard to build. Would it be fine with you if I rephrase it in some other way?

Of course! My suggestions are just that. You are best placed to rephrase in order to retain the desired meaning.

[milicag]

I just offered a modification, I think it reads more academic. Please let me know what you think. If there are any other sentences that you wish were more clear, please point them out. I appreciate your level of involvement and am very happy to polish up the paper this way.

[milicag]

From @rhosbach: Mostly the review contains alternate wordings for sentences. Feel free to edit/change as you see fit.

@brynpickering, @nmstreethran: I will address Robert's review later tonight. Please let me know if you need anything else.