Closed sneakers-the-rat closed 1 month ago
arfon
commented
3 months ago ⚡ @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
commented
2 months ago 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:
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 |
|---|---|
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 |
|---|---|
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
commented
1 month ago Pinging :) I am navigating the docs now and wishing this was merged so thought id check in
arfon
commented
1 month ago 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
Builds on https://github.com/openjournals/joss/pull/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:
I think that's pretty much it!