Restructure the documentation to make orientation easier

[fwitte]

Resolve #808
Resolve #853

Here we can develop a new version of the landing page. Right now, the idea is to have a two-layer approach:

• First layer: Landing page linking to the second layer
• Second layer: A sublanding page linking to the respective subsections

Right now there are still template images in the grid, which will be replace by better ones. The first idea would include 9 cards to start with:

• Introduction, Installation, Tutorials
• High-level overview on Network, Components, Connections
  • Specification of parameters
  • Retrieving results/getting parameters
  • Tabular overview of inputs, outputs, used equations
  • ..?
• Advanced Tutorials (links to current overview of advanced tutorials section)
• Community and Support (direct link to current community and support page)
• Advanced Features (links to overview of UserDefinedEquations, fluprodia integration, customization of components, adding new components)
• API and changelog
• Example projects, Benchmarks, Literature (links to a subpage redirecting to the respective information)
• GitHub Repository
• Contribute to development

Any thoughts on this @25Nik, @maltefritz, @jfreissmann, @TristanM-TD?

You can always view current state of draft here: https://tespy--820.org.readthedocs.build/en/820/

[n-arth]

@fwitte the landing page looks great and like (what I assume) we visioned during the user meeting. The 2 layer approach sounds like a good way to proceed, which can also be expanded easily in the future with a growing tespy. In my point of view, the 9 topics of the top layer are well chosen and the position of each topic is in an intuitive order.

Do you plan the high level overview in the style of the current heat exchangers example (maybe move the example there too)? That style would be a great entry point to start own models after the installation and first tutorials, especially for users with main skills in thermal systems rather than in programming.

[fwitte]

@25Nik, you are talking about the Network, Component, Connection overview, I guess?

I think there I would just link from that level to the different subsections. I could look like this maybe:

• Network
  • Setting up a Network, specification of units, etc.
  • Presolving
  • Solving and solve modes
  • Result retrieval and postprocessing
  • Dumping and restoring Networks
• Connection
  • Setting up connections, specification of parameters etc.
  • The different classes and their attributes/parameters
• Components
  • Setting up components, specification of parameters etc.
  • Tabular overview on all components and their parameters
  • Different types of HeatExchanger
  • Different types of Compressor
  • ...?

[jfreissmann]

Hey @fwitte, sorry for not responding sooner.

I agree with the positive feedback @25Nik gave you and like the changes you implemented since. In my opinion, the most important feature of the landing page should be a concise overview. I think, you already do that quite well with the succinct descriptions of each card, but maybe the headers could be emphasized even more compared to the bullets. I don't know how flexible Furo is in that regard, but the bullets could be e.g. use a darker font color or smaller font size. In any case, I am pretty happy with your implementation of the landing page.

[jfreissmann]

Regardless of the landing page however, an FAQ or Recipe Book/Best Practices section would improve the usability of the documentation as well. People often have an idea about what they want to do with tespy, but don't even know where to look for that and such a section of concise snippets with links to the respective doc section could improve the user experience quite a bit. What do you think about that?

[fwitte]

I implemented the suggested change. I'll kick off the subpages directing to the respective contents today.

For the FAQ part it would be nice to get some input from the community :)

[n-arth]

Hey @fwitte,
the current page looks very nice. The two level selection like in the getting started section and the links to the other pages speed up the navigation for me.

Yes, I was talking about the Network, Component, Connection overview. The way you suggested sounds good. I guess, it is a good way to have the component overview (as currently used for the heat exchangers in the examples) as the "first contact" to the components above the current components documentation. That way new users can get an overview before moving to the more in depth aspects. It would also help in the phase of generally selecting a software for a specific task in my opinion.

Additionally, I found that the pages look differently when accessed from the left overview tab or by navigating from the landing page. The headlines,... are much clearer when accessed from the navigtion on the left bar.

[fwitte]

Yes, I was talking about the Network, Component, Connection overview. The way you suggested sounds good. I guess, it is a good way to have the component overview (as currently used for the heat exchangers in the examples) as the "first contact" to the components above the current components documentation. That way new users can get an overview before moving to the more in depth aspects. It would also help in the phase of generally selecting a software for a specific task in my opinion.

This is what I was looking into, now it should be updated with a first draft of that. I added tabs with the different component modules and inside each tab the different component classes and their respective parameters (not all yet, just to get the idea, of how the overview could look like).