[UX] Review navigation: Can't get to packaging guide from https://www.pyopensci.org/python-packaging-science.html

[zackw]

There should be a prominent link from the “Community-created Python Packaging Guide” section of https://www.pyopensci.org/python-packaging-science.html to https://www.pyopensci.org/python-package-guide/ . This is where you end up if you start at the front page of the website, ignore the menus, and try to get to the packaging documentation using only links in the body text, and then you're stuck unless you think to look at the menus. (Menus are, in general, risky to rely on for essential navigation, because they may get filtered out of a reader's conscious awareness by ad-blindness.)

[pb-413]

I think I agree that it should be more obvious that it is the place to begin.

It is the destination of "What is a Python package" under "Beginner friendly Python packaging tutorials" on that page, but it looks like a tutorial among tutorials when I would call it more like the entry point for your tutorial that spans many pages.

Side note: are the tutorials suppose to be more independent (as they appear in the list under "Beginner friendly Python packaging tutorials"), or executed in sequence (which more so matches my experience so far). If sequential is desired, as it seems, consider a numbered list under "Beginner friendly Python packaging tutorials" rather than a collection of seemingly independent tutorials.

[zackw]

I see this as a separate issue from "where do I begin"? I knew I was looking specifically for the package guide and I still got stuck at the "community-created packaging guide" section of that overview page because I was blind to the menus.

[willingc]

Next action: Review the navigation pathways for usability.

[lwasser]

i've tagged this as help-wanted. I think adding a link to that page makes perfect sense and i'm 😆 that i never added that important element.

this is a beginner friendly issue. this is the block where you can add a button with a link that would be super prominant - on this page in our website

community-created:
   - image_path: images/pyopensci-people-working-together.png
     image_size: 500px
     alt: "A group of people working on a tetris like set of building blocks, trying to stack the blocks together. "
     title: "Community-created Python Packaging Guide"
     excerpt: "
     Our packaging guide is a living document that will help you navigate the Python packaging ecosystem and learn about modern Python packaging best practices.

    * Created & curated by the community

    * Reviewed by beginner to expert level Pythonistas

    * Accurate, modern & beginner-friendly

     All contributions are recognized both on our website and in the guidebook's citation.
     "

essentially you'd add a few lines to that block so it looks like this:

community-created:
   - image_path: images/pyopensci-people-working-together.png
     image_size: 500px
     alt: "A group of people working on a tetris like set of building blocks, trying to stack the blocks together. "
     title: "Community-created Python Packaging Guide"
     url: https://www.pyopensci.org/about-peer-review/index.html
     btn_label: Learn more and get involved with peer review today.
     btn_class: btn--primary

     excerpt: "
     Our packaging guide is a living document that will help you navigate the Python packaging ecosystem and learn about modern Python packaging best practices.

    * Created & curated by the community

    * Reviewed by beginner to expert level Pythonistas

    * Accurate, modern & beginner-friendly

     All contributions are recognized both on our website and in the guidebook's citation.
     "

the order of the items doesn't matter, but just adding that button element and the correct link to the package guide, would do the trick. then it would have a button like the block below ! and fit perfectly into our existing design. 

<img width="1315" alt="Screenshot 2024-06-06 at 5 21 34 PM" src="https://github.com/pyOpenSci/python-package-guide/assets/7649194/af9275e5-3155-4856-852b-3c02e5a27361">

Great catch @zackw !!

[lwasser]

@pb-413 i wonder if we could add this

Side note: are the tutorials suppose to be more independent (as they appear in the list under "Beginner friendly Python packaging tutorials"), or executed in sequence (which more so matches my experience so far). If sequential is desired, as it seems, consider a numbered list under "Beginner friendly Python packaging tutorials" rather than a collection of seemingly independent tutorials.

as a new issue. they are meant to be completed in order. we could number them easily by adding a number to each tutorial's name (also a beginner friendly task). i'm also noticing the first tutorial has the incorrect name! i'm going to turn this comment into a new issue and mark it help-wanted! another great catch!

[lwasser]

This issue actually relates to the website repo (github.com/pyopensci/pyopensci.github.io) ! i am going to move this to that repo and tag it at help-wanted!

[sneakers-the-rat]

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?