Merge pull request #1322 from sneakers-the-rat/split-author-guides

Split up guides :)

docs/_static/css/joss.css

@@ -0,0 +1,7 @@
+.ul {
+	text-decoration: underline;
+}
+
+.sc {
+	font-variant-caps: small-caps;
+}

docs/conf.py

@@ -64,7 +64,10 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['_static']
+html_css_files = [
+  'css/joss.css'
+]
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -125,3 +128,8 @@
 
 # -- Extension configuration -------------------------------------------------
 myst_heading_anchors=3
+myst_enable_extensions = [
+    "attrs_inline",
+    "linkify",
+    "strikethrough"
+]

docs/editor_onboarding.md

@@ -0,0 +1,132 @@
+# Editor Onboarding
+
+## Onboarding a new JOSS editor
+
+All new editors at JOSS have an onboarding call with an Editor-in-Chief. You can use the structure below to make sure you highlight the most important aspects of being an editor.
+
+**Thing to check before the call**
+
+- Have they reviewed or published in JOSS before? If not, you'll need to spend significantly more time explaining how the review process works.
+- Check on their research background (e.g., what tracks they might edit most actively in).
+- Make sure to send them the [editorial guide](https://joss.readthedocs.io/en/latest/editing.html) to read before the call.
+
+### The onboarding call
+
+**Preamble/introductions**
+
+- Welcome! Thank them for their application to join the team.
+- Point out that this isn't an interview. Rather, this is an informational call designed to give the candidate the information they need to make an informed decision about editing at JOSS.
+- 90-day trial period/try out. Editor or JOSS editorial board can decide to part ways after that period.
+- No strict term limits. Some editors have been with us for 7+ years, others do 1-2 years. Most important thing is to be proactive with your editing responsibilities and communicating any issues with the EiCs.
+- Confirm with them their level of familiarity with JOSS/our review process.
+- Point out that they *do not* need to make a decision on the call today. They are welcome to have a think about joining and get back to us.
+
+**Share your screen**
+
+- Visit JOSS (https://joss.theoj.org)
+- Pick a recently-published paper (you might want to identify this before the call one that shows off the review process well).
+- Show the paper on the JOSS site, and then go to the linked review issue.
+- Explain that there are *two* issues per submission – the pre-review issue and the main review issue.
+
+**The pre-review issue**
+
+- The 'meeting room for the paper'. Where author meets editor, and reviewers are identified.
+- Note that the EiC may have initiated a scope review. The editor should not start editing until this has completed. Also, editors are able to query the scope (as are reviewers) if they think the EiC should have (but didn't). 
+- Walk them through what is happening in the pre-review issue...
+- Editor is invited (likely with GitHub mention but also via email invite (`@editorialbot invite @editor as editor`))
+- Once editor accepts they start looking for reviewers.
+
+**Finding reviewers**
+
+- Explain that this is one of the more time-intensive aspects of editing.
+- Explain where you can look for editors (your own professional network, asking the authors for recommendations, the [reviewers application](https://reviewers.joss.theoj.org/), similar papers identified by Editorialbot, )
+- Point out that we have a minimum of two reviewers, but if more than that accept (e.g., 3/4 then take them all – this gives you redundancy if one drops out).
+- Don't invite only one reviewer at a time! If you do this, it may take many weeks to find two reviewers who accept. Try 3/4/5 invites simultaneously.
+- The [sample messages](sample_messages) section of the documentation has some example language you can use.
+
+**The review**
+
+- Once at least two reviewers are assigned, time to get going!
+- Encourage reviewers to complete their review in 4-6 weeks.
+- Make sure to check in on the review – if reviewers haven't started after ~1-2 weeks, time to remind them.
+- Your role as editor is not to do the review yourself, rather, your job is to ensure that both reviewers give a good review and to facilitate discussion and consensus on what the author needs to do.
+- Walk the editor through the various review artifacts: The checklist, comments/questions/discussion between reviewers and author, issues opened on the upstream repository (and cross-linked into the review thread). 
+- Point editors to the ['top tips'](editor_tips) section of our docs. Much of what makes an editor successful is regular check-ins on the review, and nudging people if nothing is happening.
+- Do *not* let a review go multiple weeks without checking in.
+
+**Wrapping up the review**
+
+- Once the review is wrapping up, show the candidate the checks that an editor should be doing (reading the paper, suggested edits, asking for an archive etc.)
+- Show the `recommend-accept` step which is the formal hand-off between editor and editor-in-chief.
+- The [sample messages](sample_messages) section of the documentation has a checklist for the last steps of the review (for both authors and editors).
+
+
+**Show them the dashboard on the JOSS site**
+
+- Point out that this means you *do not* need to stay on top of all of your notifications (the dashboard has the latest information).
+- Highlight here that we ask editors to handle 8-12 submissions per year on average.
+- ...and that means 3-4 submissions on their desk at any one time (once they have completed their initial probationary period).
+- Show them the backlog for a track, and how they are welcome to pick papers from it (ideally oldest first).
+- Show them their profile page, and how they can list their tracks there, and also what their availability is.
+
+**Other important things to highlight**
+
+- Don't invite other editors as reviewers. We're all busy editing our own papers...
+- Please be willing to edit outside of your specialisms. This helps JOSS run smoothly – often we don't have the 'ideal' editor for a submission and someone has to take it.
+- Highlight that editors will have a buddy to work with for the first few months, and that it's very common for editors to ask questions in Slack (and people generally respond quickly).
+- Scope reviews only work if editors vote! Please respond and vote on the weekly scope review email if you can. The process is private (authors don't know what editors are saying). Detailed comments are really helpful for the EiCs.
+
+**Wrapping up**
+
+- Make sure you've highlighted everything in the ['top tips'](editor_tips) section of our docs.
+- Reinforce that this is a commitment, and thay regular attention to their submissions is absolutely critical (i.e., check in a couple of times per week).
+- Ask if they would like to move forward or would like time to consider the opportunity.
+- If they want to move forward, highlight they will receive a small number of invites: One to the JOSS editors GitHub team, a Slack invite, a Google Group invite, and an invite to the JOSS website to fill out their profile.
+- If they are joining the team, make sure they mark themselves as unavailable in the [JOSS reviewers database](https://reviewers.joss.theoj.org/) (so they don't get asked to review any longer).
+- Thank them again, and welcome them to the team.
+
+**Communicate outcome to EiC**
+
+- Let the EiC know what the outcome was, and ask them to send out the invites to our various systems.
+- Work with EiC to identify onboarding buddy.
+- Decide who is going to identify the first couple of papers for the editor to work on.
+
+## Editorial buddy
+
+New editors are assigned an editorial 'buddy' from the existing editorial team. The buddy is there to help the new editor onboard successfully and to provide a dedicated resource for any questions they might have but don't feel comfortable posting to the editor mailing list.
+
+Buddy assignments don't have a fixed term but generally require a commitment for 1-2 months.
+
+Some things you might need to do as a buddy for a new editor:
+
+- Respond to questions via email or on GitHub review issues.
+- Check in with the new editor every couple of weeks if there hasn't been any other communication.
+- (Optionally) keep an eye on the new editor's submissions.
+
+## Managing notifications
+
+Being on the JOSS editorial team means that there can be a _lot_ of notifications from GitHub if you don't take some proactive steps to minimize noise from the reviews repository.
+
+### Things you should do when joining the editorial team
+
+**Curate your GitHub notifications experience**
+
+GitHub has extensive documentation on [managing notifications](https://help.github.com/en/articles/managing-your-notifications) which explains when and why different notifications are sent from a repository.
+
+**Set up email filters**
+
+Email filters can be very useful for managing incoming email notifications, here are some recommended resources:
+
+- A GitHub blog post describing how to set up [email filters](https://github.blog/2017-07-18-managing-large-numbers-of-github-notifications/).
+
+If you use Gmail:
+
+- https://gist.github.com/ldez/bd6e6401ad0855e6c0de6da19a8c50b5
+- https://github.com/jessfraz/gmailfilters
+- https://hackernoon.com/how-to-never-miss-a-github-mention-fdd5a0f9ab6d
+
+**Use a dedicated tool**
+
+For papers that you are already assigned to edit, the dedicated JOSS dashboard aggregates notifications associated with each paper. The dashboard is available at: `https://joss.theoj.org/dashboard/<yourgithubusername>`
+
+Another tool you might want to try out is [Octobox](https://octobox.io/).

docs/editor_tips.md

@@ -0,0 +1,41 @@
+# Top tips for JOSS editors
+
+**Aim for reviewer redundancy**  
+
+If you have 3 people agree to review, take them up on their offer(s), that way if one person drops out, you'll have a backup and won't have to look for more reviewers. Also, when sending invites, try pinging a number of people at the same time rather than doing it one-by-one.
+
+**Email is a good backup**  
+
+Email is often the most reliable way of contacting people. Whether it's inviting reviewers, following up with reviewers or authors etc., if you've not heard back from someone on GitHub, try emailing them (their email is often available on their GitHub profile page).
+
+**Default to over-communicating**   
+
+When you take an action (even if it isn't on GitHub), share on the review thready what you're up to. For example, if you're looking for reviewers and are sending emails – leave a note on the review thread saying as much. 
+
+**Use the JOSS Slack**  
+
+There's lots of historical knowledge in our Slack, and it's a great way to get questions answered. 
+
+**Ask reviewers to complete their review in 4-6 weeks**
+
+We aim for a total submission ... publication time of ~3 months. This means we ideally want reviewers to complete their review in 4-6 weeks (max).
+
+**Use saved replies on GitHub**
+
+[Saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies/using-saved-replies) on GitHub can be a huge productivity boost. Try making some using the example messages listed above.
+
+**Ping reviewers if they’ve not started after 2 weeks** 
+
+If a reviewer hasn't started within 1-2 weeks, you should probably give them a nudge. People often agree to review, and then forget about the review.
+
+**Learn how to nudge gently, and often**
+
+One of your jobs as the editor is to ensure the review keeps moving at a reasonable pace. If nothing has happened for a week or so, consider nudging the author or reviewers (depending upon who you're waiting for). A friendly _"👋 reviewer, how are you getting along here"_ can often be sufficient to get things moving again. 
+
+**Check in twice a week**
+
+Try to check in on your JOSS submissions twice per week, even if only for 5 minutes. Use your dashboard to stay on top of the current status of your submissions (i.e., who was the last person to comment on the thread).
+
+**Leave feedback on reviewers**
+
+Leave feedback on the [reviewers application](https://reviewers.joss.theoj.org/) at the end of the review. This helps future editors when they're seeking out good reviewer candidates.