Joss: Editorial guide

[arfon]

There's currently little/no documentation for editors of JOSS who have to interact with JOSS. We should fix this.

/ cc @mgymrek

[arfon]

I'm struggling to find time for this. Was curious if any of @openjournals/joss-editors fancied taking a crack at this? It doesn't need to be long but should ideally just outline what the editorial flow looks like from submission -- acceptance.

[rougier]

If that helps, here what we wrote for ReScience: http://rescience.github.io/edit/

[kyleniemeyer]

@arfon without remembering this issue, today @tracykteal actually started on an editor workflow document that can make up part of this guide

[arfon]

@arfon without remembering this issue, today @tracykteal actually started on an editor workflow document that can make up part of this guide

💖 that's great.

[tracykteal]

I just started a draft Google doc. https://goo.gl/kUZjnw If anyone wanted to fill in details or see what's missing that would be great.

After it's less draft-y I'll move it over to a Markdown document. I was thinking of just putting it in https://github.com/openjournals/joss/tree/master/docs, but let me know if it should go somewhere else.

[kyleniemeyer]

It might be nice to have it easily accessible via the website, perhaps on a new "Guides" page? A few of us at SciPy talked about the need to put help about some other things, such as guides to appropriately citing software when a JOSS article is available, or how we recommend authors set up the GitHub+Zenodo integration for easily citing specific versions.

[lheagy]

@kyleniemeyer has been very helpful getting me on-boarded as an editor and giving pointers on the first article I have been editor on!!

Through the process, I have documented a few thoughts below on information that would be helpful to have posted and accessible.

Purpose of each stage of a submission

I think the purpose of each stage (eg. [PRE REVIEW] / [REVIEW]) could be stated more explicitly, particularly for the pre-review.

For example, something along the lines of

The purpose of the pre-review stage is to
- assess if the submission is within the scope of JOSS
- check that the submission satisfies the submission requirements http://joss.theoj.org/about#author_guidelines 
- find suitable reviewers

would communicate to everyone involved what the steps and also give us some direct items to point to if there are any hang-ups / delays.

Similarly, the Review issue starts with the instructions, not with what is meant to be accomplished

The purpose of the review process with JOSS is to ... 

These are perhaps somewhat obvious, but having it explicitly stated gives everyone involved a benchmark to assess against.

Points that should be documented somewhere

One thing I encountered (that I didn't find documented anywhere):

• reviewers need to give explicit approval on github (the reviewer I was working with was new to github and was conversing mainly by email, but it is important to have a public, digital record of their approval associated with the submission)

Practices / Workflow

• are there any practices around who applies the "accepted" label - @arfon, the editor or either?
• it might be worth archiving a "request for review" email somewhere to give editors a starting point for crafting an email that includes appropriate links (what is JOSS, what are we asking of you as a reviewer, etc). It doesn't need to be standard or anything, but could serve as a resource for helping ensure important information gets communicated

An FAQ

Is there an FAQ set up (that is easily editable by us)? There were a couple minor questions that came up that would be worth making accessible to authors and editors

• eg. I go the question: Do Zenodo and software versions need to be in-sync?

[tracykteal]

Thanks @lheagy. We can combine this and the Google doc into a Markdown file and put it in the docs directory. https://github.com/openjournals/joss/tree/master/docs

I could start the Markdown with the Google doc and then maybe you could put these components in?

[labarba]

The email text I have been modifying gently and sending to request reviews goes like this:

Dear Dr. Jekyll,

I found you following links from the page of The Super Project. This message is to ask if you can help us out with a submission to JOSS (The Journal of Open Source Software), where I’m editor.

The submission is titled:
"great—a project for science"

… and the code repository is at:
https://github.com/<…>

JOSS is a free, open-source, community driven and developer-friendly online journal (there is no publisher seeking to make revenue from the volunteer labor of researchers!). The journal aims to bridge the gap of research software receiving citation credit.

The review process at JOSS is quite unique— we are interested more in code review, and the “paper” is in fact a summary of the software functionality and statement of need.

JOSS reviews involve downloading and installing the software, and inspecting the repository for key elements.
http://joss.theoj.org/about#reviewer_guidelines

Editors and reviewers post comments on the GitHub issue tracker, openly, and authors respond to the comments and improve their submission until acceptance (or withdrawal, if they feel unable to satisfy the review).

In case you want to know more, we just wrote a paper about JOSS: its motivation, design, and the assessment from its first year of operation.

The preprint is out on arXiv:
https://arxiv.org/abs/1707.02264

Would you be able to review the bsym submission for JOSS?
Or, if not, could you recommend someone from your team to help out?

Kind regards,
Lorena.

[tracykteal]

Thanks @labarba. This is great. Could we put this template text in as a file too, and link to it from the Editors guide?

[Kevin-Mattheus-Moerman]

@tracykteal I can help to evolve the content in the _docs_ folder into a website using Jekyll pages.

[kyleniemeyer]

@Kevin-Mattheus-Moerman that would be very helpful—it would be good to have a separate joss.github.io (for example) page with these docs/guides, that can be updated separately from the main JOSS website.

[labarba]

I copied the content to the Google doc into a markdown in the docs/ folder, and will edit there.

[pdebuyl]

Hey, the guide being up at https://joss.readthedocs.io/en/latest/editing.html this might be closed.