search

ropensci / statistical-software-review-book

Guide for development and peer-review of statistical software
https://stats-devguide.ropensci.org
43 stars 11 forks source link

Dev #15

Closed mpadge closed 4 years ago

mpadge commented 4 years ago

@noamross @maelle @karthik I've pinged you all as (potential) reviewers on this PR. Any insight would be greatly appreciated! You can view the PR preview here. The sections I would particularly like feedback on are Chapters 4--6, and maybe 8. The aim here is to get a bare minimum with which we're sufficiently happy in order to (1) Merge with master; and (2) Email the board members to ask for their feedback

Please ask any questions here, comment in-line on the various commits, ping me on slack, whatever's best for you. Thanks in advance!

maelle commented 4 years ago

Any specific aspect you're looking for feedback on? (Fine if not :-) )

mpadge commented 4 years ago

Any specific aspect you're looking for feedback on? (Fine if not :-) )

... any and every thing. That said, the Proposals sections which are at the end of most chapters are intended to guide feedback, so anything in response to those would be most useful

noamross commented 4 years ago

Great work Mark, I think in general we should merge this and start seeking feedback, with a focus on Chapters 4 and 7-8. My one major piece of feedback at this point is that in Chapter 8 you put a lot of focus on the implementation of review via GitHub templates and threads, while I think stepping back and talking more about the general structure of the process would make more sense. First, there are a lot of different implentation approaches we could take (submittal by form, or submittal by devtools::release()-like function in the R console.), but I think also these are secondary to the stuff about the actual nature of interaction. There's nothing about different ways to actually structure the review process - e.g., reviewer anonymity, broader community review, or how multiple rounds of review may be handled, or the specific tasks or roles of reviewers. Some of the stuff you discuss in Chapter 7, especially life-cycle options (e.g., what about the proposed life cycle statements by authors?) definitely deserves more airing in the undeveloped pats of 8.7-8.10. I'd make a proposal for a bronze/silver/gold rating in 8.7.

maelle commented 4 years ago

Great work! A first very small piece of feedback, I see some typos, e.g. "feeedback" and "Lacncaster University" and was wondering whether you could run a spell check? Not necessarily before merging. I don't have a good solution for this, spelling doesn't ignore cross-references as far as I remember.

mpadge commented 4 years ago

Another thing that was on my mind whilst reading this is that the book mixes guidance/processes and meta thoughts such as "this is why it is important to define categories". Later, do you plan to have another home for such meta thoughts?

That's a keen insight! I hadn't yet thought about that, and don't have an answer. I just have an awareness of a burgeoning tension in regard to what this document will become. Mostly, it should serve as a set of practical guidelines, and for provision of information for the diverse range of folk who might engage with the system. The more it moves towards that, the more that such meta thoughts will just become distracting and counter-productive. I've already jettisoned quite a few, and just had a suspicion that it would suffice to just keep on doing so, but maybe it will be worthwhile having some kind of "meta home" for such things? I'll definitely keep that in mind - thanks!

Last thing regarding seeking feedback, just in case you might ignore and find interesting: https://github.com/benmarwick/bookdown-ort (never used it myself)

I hadn't seen that - thanks!

mpadge commented 4 years ago

Great work! A first very small piece of feedback, I see some typos, e.g. "feeedback" and "Lacncaster University" and was wondering whether you could run a spell check? Not necessarily before merging. I don't have a good solution for this, spelling doesn't ignore cross-references as far as I remember.

Thanks, i had indeed not done any kind of spell check. All fixed.

maelle commented 4 years ago

Out of curiosity, how did you do the spell check?

I'm not really happy with the dev_guide workflow.

maelle commented 4 years ago

I've already jettisoned quite a few, and just had a suspicion that it would suffice to just keep on doing so, but maybe it will be worthwhile having some kind of "meta home" for such things?

Since you have these thoughts and have already written many of them, if I were you I'd archive them somewhere just in case. It might be useful in some documents later.