Context

We recently suggested improving the structure of the documentation website, to improve clarity, and especially the "first contact" with the documentation. This is not necessarily a lot of work, but requires a bit of input, discussion and coordination.

@DahyannAraya, @ValentinGebhart and I had a look at other documentation, and agreed on the following points not ordered by importance (which I detail a bit more below):

1. Switching from a "everything in the sidebar" to a "main category header & sub-categories sidebar" format.
2. Making "Getting started" a main category by itself, with a landing page, and a few sub-categories, which all should be the less technical possible (few if no code, brief instruction, mostly conceptual).
3. Rename the "Tutorials" main section to "User guide" (And maybe have tutorial as a subsection?)
4. Create landing/index pages for all header sections (notably API)
5. Remove Miscellaneous section, put Authors, Changelog and Contribute as top sections.
6. Move content around in these sections for consistency
7. The idea is to focus on restructuring and moving around rather than creating new content. But still, some additions (or rewriting) may be required, specifically for the "Getting started"

Reflexion & Details

Main argument for 1. is that too much information is shown in the sidebar on all pages, which are not always relevant (for instance non dev users are presumably not interested in the content of the developer guide), also I think headers improve readability. A possible other solution would be to keep the sidebar and just collapse the non-currently visited main sections by default (but that would also require restructuring anyway as what is currently shown are a collection of tables of content where each "main section" is just their title)
Points 2. and 3. (and 4.) mostly comes from other documentation websites (pandas, numpy, geopandas). It could be worthwhile to further the reflexion on this as there are many possible options. For instance, maybe we could have an "About" page similar to geopandas, although this might be redundant with the future new website.
For 4. specifically, it is sort of required by 1., and I think it would improve readability for a low new content cost. For instance, the current API main page is quite dry at the moment and would benefit from a landing page such as the one for geopandas or pandas.
For 5. I definitely think the Miscellaneous section itself should disappear, I am less sure on the best approach regarding its content.

Points 6. and 7. : The "Getting started" landing page should have a very brief intro similar to the Pandas intro with no or very few code, mostly figures and links to relevant tutorials. Preceding could be what is in the current "Introduction" page. A lot of the content of the "Overview" tutorial could also go in the new "Getting started" section (either on its index or in subsections, notably the "Python introduction" could be such a subsection).
The tutorials landing pages (Hazard, Exposures, Impact, ...), should have brief explaining paragraphs. Maybe some tutorials may benefit from more detailed names?

Of course the debate on these changes/suggestions is open (notably, @peanutfun I think you spent a lot of time on the current website, so if you have strong opinions on some of these please don't hesitate to express them!). From what I have seen in other open-source project, taking time to reflect and decide on the UI/UX/Content of the documentation is worth it!

Distribution of work

I created a new branch feature/documentation-restructuring with the new theme, and the new "skeleton", but haven't moved anything or created any new content yet.
Work can probably be split up like this:

1. Someone handling the newish "Getting started" section
2. Someone refreshing the "User guide" section tutorials (not a lot to do, I assume, mostly index pages, and streamlining possible redundancy with Getting started)
3. Someone handling "the rest" (API reference, Miscellaneous), also not too much to do (?)
4. Someone to make sure that no links are broken and that the transition to new structure works well etc.

(I don't think the Developer guide needs any refreshing? Just to be linked properly within the new structure.)

I am happy to handle 4. (which, I'll be honest, is not a lot of work now that a skeleton version exists) and provide help for technical aspects if they arise.

@ValentinGebhart, @sarah-hlsn, @NicolasColombi, @elianekobler, you all mentioned you were OK contributing to this topic, can I leave it into your hands to decides on who does what? (5 is probably too much I think tbh)

Technical aspects

For 1., I had to change the website theme from sphinx-book-theme to pydata, these themes are really close so it doesn't change much a part from the headers, here's a rendered overlook:

I think I already made the little technical changes required for it to work well (for instance, having the logo in a non-tiny size), but be on the lookout for bugs/artefacts.

I have already created placeholder .rst files for the main sections I mentioned, although they are quite empty at the moment. What remains to be done is to put some content and put the table of contents part that will link the subsections, notably the notebooks for the tutorials. You can have a look at how this is done in the "index.rst" file of the root dir of the documentation.

I don't know how much you know of rst formatting, but I refer you to the theme documentation, which I think is quite clear. Most interesting pages for you are probably Examples > Kitchen Sink, User guide > Theme specific elements and User guide > Sphinx Design components

To build the documentation locally and see your changes in effect, follow the associated guide. Don't forget to install the development dependencies (pip install -e ./[dev] when installing). The new theme was already a requirement of the previous one I think, so it should not need anything.

Note that sphinx (the documentation compiler) sometime does not properly update the html files, so you might want to run make clean html if you fail to see your changes. There are also a few warnings during compilation, which I will try to look into, but shouldn't be too concerning.

Thanks for reading this far 🥔