Restructuring of the user guide

[schroedtert]

Our user guide gets quite extensive (which is a good thing!), but with this, I'm a bit worried about the readability and if all use cases can be represented here. As we try to document each function there by using the same data as an example, some parts cannot be represented nicely. The documentation of the new method for fundamental diagrams #242 has no good place to be placed on the website (same for the fundamental diagram notebook), as it needs other data. When we add functions for single-file experiments, or other special cases, we need to find a way to handle this.

My first idea was to split the notebook, into several notebooks for special categories, e.g., density, speed, fundamental diagrams. This way, each topic can be placed in a specific category and be documented there with the needed data and setup. The downside of this would be that, referencing other functions may lead to jumping to different pages and not on a single page. This could look like this:

This is open for discussion, if you have any other ideas on how to improve the structure, let me know.

[chraibi]

Instead of fully splitting into separate notebooks, can we consider using a hybrid approach?

For example:

• User Guide: Central notebook with high-level summaries and key workflows.
• Detailed Appendices: Detailed, standalone notebooks for advanced or specialized use cases (e.g., CECM, fundamental diagrams, Smoothing, Flow through bottlenecks, etc).

This way, users can start with the main guide and navigate to deeper dives only when needed.
For me personally, the user guide is a place I start from, to know how to apply a certain function.
When I get a taste, I check the API for arguments and more details.

However, to satisfy my laziness (putting everything together), I would appreciate more comprehensive and hermetic examples.

Example Structure:

• User guide:
  • Overview of analysis capabilities.
  • Links to specialized topics.
  • General examples with broadly applicable datasets.
• Specialized Notebooks:
  • Focused, topic-specific examples with detailed explanations and datasets.

[ThoChat]

I do agree with @chraibi.
In my opinion, the User Guide should remain as a standalone as, there should be a unique source of information that users should go to in order to understand how PedPy works. This being said, it would also be nice to have a dedicated Notebook section with examples and special case studies like for the Fundamental Diagram, continuity equation and so on.