Talked with @OriolAbril a bunch. Here are some thoughts I have on getting the website to a state where v4 can be released (a lot of them are already on the roadmap from Oriol):
I think it’s confusing for users as they are not sure which to visit (at least between the first 2). They all have different versioning and code/repos, so harmonizing the code is probably out of scope. However, we can make them look similar. @OriolAbril had the idea to give them all the same navbar to make them look more similar and maybe the user doesn’t notice. I really like that.
The current navbar on the docs repo has:
I like this one the best and I think we should adopt it everywhere. Here’s how I propose the items and contents should be:
Home (currently spread across docs home and pymc.io, I propose we use pymc.io for this):
What is PyMC
Highlights (Fast, Modern, User-Friendly etc)
Links to installation instructions
Announcements
Examples (using PyMC example gallery — PyMC documentation but instead of its main page with descriptions about NBs, bring back the gallery like on v3 docs (not sure what to do with tags, maybe we make them invisible for now until we can combine it with the gallery). I also think here we can actually merge in gallary from the tutorials-selector from v3 and add these as additional categories. That way, all the NBs are in the same place.
I think we should remove the “Contributing” item. Here’s why: There are 4 types of people who could come to the site:
People who don’t know what PyMC is (newcomers)
People who already use PyMC and want to learn how to use it / solve their current problem (users)
People who want to contribute (potential contributors)
People who are already contributing (developers)
To narrow scope, I think we should optimize the website for newcomers and users, and have GitHub be optimized for potential contributors and developers.
I think part of the confusion between #1 and #2 is that #2 contains a lot of information that isn’t exactly “documentation”, but was placed there because we didn’t (at the time) have a place like #1 (except the README shown on github). If I were to land as #1 and saw a link to “Documentation” I wouldn’t expect to get what is currently at #2, (e…g, a high-level introduction to the package, its niceties, etc.). I would expect documentation. To me, it makes sense to try and get pymc.io to be landing page and have documentation (API) and examples linked from there (along with other more static pymc info).
I personally would keep pymc.io as a separated website. It is a different domain and it might be even more confusing for users to see the navbar maintained but different domains. AFAIK, all similar projects have multiple clearly separated websites:
I think that as @cluhmann points, now that we have pymc.io we can restructure our websites (common navbar or not) to have a more sensible and coherent strucutre. IMO, the key, most important and irrenounceable difference between the websites are the different versioning schemes (which means they need to be build and updated independently from one another).
As I commented on slack:
pymc.io has no versions. It is a single website that gets updated automatically
docs.pymc.io has versions tied to the versions of the pymc library, and defaults to showing the docs of the stable version
docs.pymc.io/projects/examples (aka pymc-examples) has independent versions/snapshots (2-3 a year, not necessarly tied to pymc releases) and defaults to latest . That means that new or updated notebooks show on the default website immediately instead of having to wait for a new release to see the changes
So answering which pages we want to have in each versioning scheme should indicate where should they be. i.e. we should probably move the community, maybe even contributing section to pymc.io as I don’t think they need to be versioned following pymc releases. The homepage should also imo be pymc.io because I don’t think the homepage should be versioned, it should have the highlights most important info about the library, not version specific content…
I very much agree with making the nabvar between docs and examples to be the same.
Also agreed on having the homepage at pymc.io. I would have more info on the homepage though (whatever theme/navbar we choose). See this comment for longer description on this.
Tags and a gallery looking page are completely independent, the tags are on the sidebar, we need to update the page content to write these cards with notebook titles. This should be possible combining code from pymc/gallery_generator.py at v3 · pymc-devs/pymc · GitHub (to get the images from the notebooks) and arviz/gallery_generator.py at main · arviz-devs/arviz · GitHub (to structure how to automatically write the rst/markdown page with the cards using sphinx-design). That being said, I don’t really know how sphinx extensions work and don’t want to maintain this alone if we go down this path.
I strongly disagree with removing the contributing element/section though.
I think we should strive to make the division between user and contributor as blurry as possible, and I think this goes against this
Most of the content is currently code based with some doc centric pages, but I think we should work on extending this, and not all contributions require using GitHub.
I think it is much better to read pages rendered from the docs. We can use note/warning/tip boxes to highlight specific sentences, we can use tabs/dropdowns for alternative content or recommendations that are not vital to understanding all the page, we can link between pages and to api pages much more easily and robustly (we already use all this in different pages of the contributing section)
Do we want all websites to look the same and share the navbar or only the docs and examples ones?
What should be the items (and order) in the shared navbar?
Who can work on and maintain the sphinx extension to generate the examples landing page with cards?
What sections should there be in the main homepage at pymc.io
What should be the content in the learning or user guide section of the navbar
Some extra context. The new learning page doesn’t only have the content of the old page, it also has more “user guide” style content like the notebooks on core features. Those are a very small subset of notebooks that we decided should be versioned like pymc releases (and are therefore run on readthedocs when building the docs).
and also corollary from this is that closed questions are:
As an average user of ‘apps’/‘libs’ that use multiple domains, I always get confused when the navbar changes across the domains. Actually I seldom look at the domain.
Moving from domain to domain, changes in the navbar typically make doubt whether I am still on the ‘official’ site(s), maybe looking at outdated stuff, etc
So my vote (or rather 2cts) go to ‘keep the navbar constant across domains’
No installation, community, blog or about the project section? Everything must be inside one of these navbar sections, where would the blog, current community page, history, ecosystem, testimonial sections be if using these elements only? Or the installation instructions if we make the learning page be the v3 one
Should the search bar continue to be on the navbar? And icons on the right?
Re search bar, I think it would be crazy that the search bar returned different results depending on the page the user is in, given we are trying to hide the fact they are different websites from them. I can think of a way to solve this using the subprojecta feature which would then mean making everything a subproject of pymc.io and everything being hosted at pymc.io/projects/(docs/examples/experimental)
As I commented on github, here I would also add highlighted libraries that build on top of pymc and maybe some links to popular examples.
Installation instructions: We could add this, like scikit-learn does. But they are also on the home page. Correct me if I’m wrong but I think we don’t really currently have an installation page because we have 3 different installation instructions and I think that’s a good enough solution for now to link from the home page.
Community: Good point, maybe we should add that too. Maybe there we add the a link to the blog?
History: I don’t think we need that, could have that be a wiki page
Ecosystem: I don’t think we need that, we could have that as a section on the homepage as you say further below.
Testimonials: We could also have a few good ones on the home page
If we want to add just a bunch we could do what sklearn does and have a “More” fold-out that lists all of them that are important but not that often frequented that it needs a spot in the main navbar.
I would yes to the icons on the right.
Search bar: It’s a good issue you raise and the solution seems fine. I actually never used that feature and don’t have a strong intuition as to what results I would expect. Just search across everything, blog posts, tutorials, announcements, API? So I could do without the search bar.
