Enh: revisit the site navigation for pyOpenSci

[lwasser]

I think there are two related things in this issue: first is that the pages on the main website can get you lost on the way to the packaging guide, with the page in OP being a good example. second is that the menus imo are also a bit confusing - so both in-page and navbar navigation could use a bit of cleaning up.

First on the in-page stuff: these pages seem like near duplicates to me:

• https://www.pyopensci.org/python-packaging-science.html

• https://www.pyopensci.org/learn.html

• https://www.pyopensci.org/python-package-guide/

Each seems like an index of the packaging guide, but it's not clear that's the case. I think there should ideally be only one page like that, and I think that's related to the overall structure of the site.

Currently the structure of the main site is like this (abbreviated from navigation.yaml):

main:

  - peer review:

    - about: /about-peer-review/

    - partners: /partners.html

    - packages: /python-packages.html

    - peer review guide: /software-peer-review/

  - packaging:

    - resources: /python-packaging-science.html

    - packages: /python-packages.html

    - guide: /python-package-guide/

  - learn:

    - tutorials: learn.html

    - blog: /blog/

    - ask a question: https://pyopensci.discourse.group/

  - community:

    - our community: /our-community/

    - connect: https://pyopensci.discourse.group/

    - handbook: /handbook/

  - get involved:

    - volunteer: /volunteer.html

There are three other major independent repos: the handbook, packaging guide, and review guide. The handbook i think is good, but the packaging and review guide nav layout are also a bit confusing to me. I like keeping the various guides in separate repos for the sake of not having a gigantic website repo that everyone is afraid to touch, but also ideally there would be a sense of continuity in navigation between them. Once you get into any of the other guides, the structure from the main site is lost and it's not altogether clear from an outside observer why /python-package-guide/ would be a fundamentally different thing than python-packages.html. From the main page, it's also not clear that the packaging guide also covers tests and docs (since it's under "packaging")

The tutorials are nested within the package guide, so they're at python-package-guide/tutorials/ and are basically a parallel set of guides from the rest of the packaging guide, but that nesting makes it somewhat unclear to me that they are intended to be covering some of the same information but geared towards a different audience/with more of a step by step design. there are some other ux things i think could be improved there but i'll keep this focused on structure.

I think we should refactor the site like this:

• split up the packaging guide into five repos:

  • common: a template repository, package, or regular repo we use as a submodule within the other repos that contains common things like styles and config

  • tutorials

  • packaging

  • documentation

  • tests

• simplify the hierarchical structure of the site like this:

- packages:     /packages.html

- peer review:  /peer-review/

  - about:      /peer-review/about

  - guide:      /peer-review/guide

  - partners:   /peer-review/partners

- learn:        /learn/

  - tutorials:  /learn/tutorials

  - packaging:  /learn/packaging

  - docs:       /learn/docs

  - tests:      /learn/tests

- community:    /community

  - blog:       /blog

  - discussion: https://pyopensci.discourse.group/

  - handbook:   /handbook/

  - volunteer:  /volunteer.html

We might be a bit hampered by github pages and the relationship between repo names and paths, but there are ways to work around that to get the nav structure we want. We can (and should) leave redirects behind from the old locations so we don't break inbound links.

I think that will make it easier to navigate bc then there is one clear place for an index for each of the categories, and then each of the subcategories/separate repos can have a clear "back up to..." that shows breadcrumbs back to the same navigation structure - so eg. if i'm in the docs guide, i would see "back up to: learn, main page", so theres one clear way to get to the other guides or back to where i came from (ideally we would just keep the whole nav tree everywhere, but that's hard to coordinate across multiple repos, one step at a time).

In the meantime, if/until we split up the packaging guide repo, I can PR the navigation structure above, substituting the current URLs for these ones. And directly in response to the OP, i think we basically don't need that page/it should be merged with the index of the packaging guide.

what ya think?

Originally posted by @sneakers-the-rat in #441

[InessaPawson]

@sneakers-the-rat The proposed website structure looks great!
For additional inspiration, I highly recommend Michael Chow’s talk at SciPy’25, in which he took us on a deep dive into information and technical documentation architecture design: https://www.youtube.com/watch?v=lHCOVqCZRFw Among the most insightful talks on this topic in my recent memory.