rearrange the checklist into actionable items and advice sections

nsryan2 commented 2 years ago

Summary of changes

This PR rearranges the checklist to have lists of actionable items and then sections for grammar, style, and advice on clarity. It also adds grammar rules for punctuation around quotations (lines 81 and 82) and about the prepositions 'of' and 'for' (line 90). Other than those specific lines, I didn't add anything new.

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)
[x] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
[x] I have read the CONTRIBUTING document.
[x] My code follows the code style of this project.
[ ] My change requires a change to the documentation.
[ ] I have updated the documentation accordingly.
[ ] I have added tests to cover my changes.
[ ] All new and existing tests passed.

Associated Issues and PRs

Issue: #
Closes: #260

Associated Developers

Dev: @

Checklist for Reviewers

Reviewers should use this link to get to the Review the Checklist before they begin their review.

nsryan2 commented 2 years ago

The idea was that the first two sections are an actual checklist of actionable items for writers to go through. The sections about enhancing or the additional math comments are not actionable items, more so advice, or grammar rules

nsryan2 commented 2 years ago

What do you think about changing the sections headers to:

## checklist
### writing
### tables and figures

## enhancing your writing
### style
### grammar
### conciseness 
### using latin
### additional math comments

This might make it clearer that the first two are action items for writers, and the others are advice and rules.

gwenchee commented 2 years ago

Regarding this:

The idea was that the first two sections are an actual checklist of actionable items for writers to go through. The sections about enhancing or the additional math comments are not actionable items, more so advice, or grammar rules

It's confusing because some of the actionable checklist items do fall in the enhancing clarity and enhancing style subsections. And the way you split them up is based on how they were worded. For example Get rid of passive voice (is/was/are/were/be/been/am + past tense verb), replace with active voice sounds actionable, but it could be easily reworded into avoid passive voice (is/was/are/were/be/been/am + past tense verb), and instead use active voice and put into the enhancing clarity section.

Having two sections: checklist and enhancing your writing might suggest to students that the checklist is mandatory, while the enhancing your writing section is a suggestion. I think the original intention of the writing checklist is that all of it is mandatory, thus a checklist to be completed.

My suggestion is to keep the checklist and divide it into sub-sections. If you want, you could also reword some of the bullets with more actionable wording.

nsryan2 commented 2 years ago

Great feedback! I wasn't originally thinking of it like that, but that makes more sense. I'll rework it a little bit in that framework!

nsryan2 commented 2 years ago

Ok, @gwenchee, I took a crack at making them action items (some of them just can't be them without making it weird IMO). They're all checklist items now though, and I changed the first section to be for reviewing (let me know what you think of that in particular). I didn't really want to consolidate it into the other lists because I think if they get much longer it might be necessary to break the lists up even more so that it's readable.

gwenchee commented 2 years ago

I'll merge once you resolve the branch conflicts @nsryan2

nsryan2 commented 2 years ago

@gwenchee Awesome! Everything should be all good to go!

arfc / arfc.github.io