What should a new ISIS homepage look like?

[AndrewAnnex]

As per the November meeting notes #150, we decided to gather more ideas and requirements for a notional new centralized homepage for the isis project. Note that there are no definitive plans to implement anything yet, we are just gathering information in this issue.

The problem

Currently, web resources for ISIS users are scattered across several locations including GitHub, Astrodiscuss, the old ISIS website, and blog posts. When users (in particular new ones) try to start learning how to use isis, it quickly can become a problem to find up-to-date information and confusing where to get it. It’s also not always clear which version of the documentation you are reading.

That said we also want to gather some information about this problem to more fully develop the conceptual solution below.

Conceptual solution

There needs to be a new, modern, centralized homepage for ISIS that provide links to or eventually fully contains resources such as:

1. News and Release Notes
2. Install guide
3. Tutorials including notebooks
4. Forum/community links
5. FAQs
6. Software Docs (optionally versioned, using sphinx)
7. API Docs (optionally versioned, using breathe+Doxygen+sphinx)
8. …

A critical feature is the ease of use for contributing updates to the page. Ideally the website state would be in version control and could be quickly updated as needed through PRs from the community.

Examples

Many large software projects have similar websites

1. www.opencv.org (main links at homepage)
2. www.gdal.org (big sphinx site)
3. https://www.kubeflow.org/ (Hugo site)
4. www.qgis.org
5. www.tensorflow.org (has both api docs and higher level stuff)

Possible Solutions

A possible solution to this problem would be to use a static site generator like Sphinx or Hugo. GitHub action CI could be used to generate the static site and deploy it to the github.io page for isis.

Unfortunately, sphinx is more adept to documentation for software while Hugo is more for generic static sites, but it should be possible to use both together. Hugo has a number of great themes like Docsy that may make this easier to bridge. To start it maybe sufficient to do the easier priorities first with a Hugo based solution.

On the other hand, gdal.org looks great and you can do links and stuff in sphinx, seems like you could also just go purely with sphinx although replicating versioned hosting like read the docs with github ci may take some effort.

More research is needed/a potential prototype could be made to figure this out.

Questions:

1. what are we missing from the requirement list?
2. what else are we missing?
3. can we make a prototype to try out some options?

[victoronline]

I would like to comment on a few items in the requirements list mentioned above.

Regarding requirement #6, I'd like to emphasize the need for versioned Software Docs being a high priority, rather than an optionally required. I believe only having the current documentation version on a site causes a lot of confusion our users are mostly not working on the bleeding edge version.

Additionally, our users would like to emphasize that having all information on one site would be a huge benefit. If the solution does not include creating an entirely new site, at minimum, having all other sites forward to one main site, would be beneficial.

[AndrewAnnex]

I think versioned software docs are not a blocker for starting to make this website, but it does depend ultimately on how things are executed. If a sphinx website, hosted in the isis repo, is acceptable then we get versioned docs essentially for free, if instead the site simply links to other pages then the other page could have the current software docs and then transition to a versioned form later. Theoretically this would already be possible by checking out the source for each release, building the docs, then adding them as a static link to this new page, just as an example. But hopefully a more elegant technical approach can be adopted. There are many ways to accomplish this goal in the end, both with independent repos, different tools, etc, but we do need to find the low-cost path forward