Split up guides :)

[sneakers-the-rat]

Builds on #1321 (sorry for non-modularity, i just sort of figure that one had to get merged since recommonmark is unsupported and this will definitely take longer to review)

Don't be frightened, looks like a lot of changes but nothing of substance is actually changed. I had a bit of trouble following the editorial guide since it seems to come out of order for me, and it's hard to use as a reference since it's all on one page!

I figure the other guides are the same, and it seemed strange to me to have the author guides and reviewer guides all mashed together, so i split them up!

Specific things, aside from splitting:

• Fix the markdown inline examples: add css to make them work, and switch from .rst to myst syntax
• Put editorial overview at top instead of bottom
• Rename "After reviewers recommend acceptance" to "post-review" to line up with other headings
• Group ropensci and AAS sections as "collaborations"

I think that's pretty much it!

[arfon]

⚡ @sneakers-the-rat thanks for working on this! A few quick questions:

Will this change any links to the docs? If so, we should probably audit the JOSS site and the review issue templates to make sure those links are all still 👍 .

Would it be possible to have a couple of screenshots of what the structure will look like now?

[sneakers-the-rat]

Got a second to return to this, sorry for the delay.

Will this change any links to the docs?

I didn't remove any pages, but any links that are for specific sub-anchors within a page will be broken, yes. So, for example, I split up all the stuff about how to format a paper into its own page where before that was all in submitting. If you let me know all the sites that would need to be audited for changes in links then i can make companion PRs to fix them.

Would it be possible to have a couple of screenshots of what the structure will look like now?

Attaching a zipped HTML build in this comment here: html.zip

Some screenshots:

TOC

Main

Make clearer distinction by roles, so authors, editors, and reviewers have all their stuff in one place (eg. authors can find paper formatting instructions more easily, and know that the "Joss Policies" also applies to them).

Before	After

Submitting

Reordered to be more linear, and grouped together similar topics for easier skimming, where before things were sorta splayed out across top-level headings in different parts of the docs (eg moving "proprietary languages" under "policies")

Before	After

Editor Guides

Make the guide linear - start with an overview, pre-review, review, post-review. Split out "onboarding" "expectations" and "tips" to separate pages so they are more visible, and they are also relevant at different times than during an actual review.

Before	After

[sneakers-the-rat]

Pinging :) I am navigating the docs now and wishing this was merged so thought id check in

[arfon]

Pinging :) I am navigating the docs now and wishing this was merged so thought id check in

Love it. Thank you @sneakers-the-rat – this is a big improvement for everyone.

I didn't remove any pages, but any links that are for specific sub-anchors within a page will be broken, yes. So, for example, I split up all the stuff about how to format a paper into its own page where before that was all in submitting. If you let me know all the sites that would need to be audited for changes in links then i can make companion PRs to fix them.

Thank you. The main places are the JOSS site (e.g., https://joss.theoj.org/about) and the reviewer/editorialbot templates which I believe are all in https://github.com/openjournals/joss-reviews/tree/master/.buffy/templates

Cheers
Arfon