Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Split up guides :) #1322

Merged
merged 3 commits into from
May 9, 2024
Merged

Conversation

sneakers-the-rat
Copy link
Contributor

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
Copy link
Member

arfon commented Mar 13, 2024

@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
Copy link
Contributor Author

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
Screenshot 2024-04-16 at 6 57 01 PM Screenshot 2024-04-16 at 6 56 41 PM

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
Screenshot 2024-04-16 at 7 00 13 PM Screenshot 2024-04-16 at 7 01 58 PM

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
Screenshot 2024-04-16 at 7 04 01 PM Screenshot 2024-04-16 at 7 04 23 PM

@sneakers-the-rat
Copy link
Contributor Author

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

@arfon arfon merged commit 79fb00e into openjournals:main May 9, 2024
1 check passed
@arfon
Copy link
Member

arfon commented May 9, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants