search

calliope-project / calliope

A multi-scale energy systems modelling framework
https://www.callio.pe
Apache License 2.0
276 stars 89 forks source link

Difficult to navigate through the menu #601

Open tud-mchen6 opened 1 month ago

tud-mchen6 commented 1 month ago

Description

I personally find it difficult to navigate through the website if I have in mind what I want to find. I try to summarize the issues below:

  1. Information about one topic can be found in various different sites. For example, regarding .csv inputs to the model, there are both 'introduction' and 'tutorial' for data_sources. Another example could be that the information about slicing data is spread across the 'Math syntax' page.
  2. I do not always immediately understand the menu items, e.g., what is 'components' and 'syntax'? For total beginners this might be confusing.
  3. There is potentially overlapping information in different sections in the root menu. For example, 'Creating a model' could overlap with 'Defining your own math'.
  4. In general, the number of items in the root menu is a lot for me. Potentially this could be reduced, e.g. by moving 'Pre-defined math' and 'Defining your own math' into 'Creating a model'. The root menu seems to follow the sequence of modelling process, first download, then create, then run a model... then stick to this timeline and put things related in place.

But again, these are all my personal opinions and preferences.

Related links

Math syntax: https://calliope.readthedocs.io/en/latest/user_defined_math/syntax/ (I write it because I have to write something in this box.)

Version

v0.7.0

Proposed change

No response

brynpickering commented 1 week ago
  1. There's the introduction to a concept and then a more in-depth tutorial on its use if you're having trouble using it. I think that's a reasonable approach to documentation.
  2. Agreed that it can be confusing and you're looking in parts of the docs that really require you to already have quite a strong grasp of the basics before diving into them. This links to (3) and (4) that we should probably better separate out what is basics/intro stuff and what are advanced topics.
  3. They have two different purposes. The Pre-defined math section is primarily a reference document for users who are just running Calliope who want to make sure the underlying math is sound (and that we are being transparent about this math). The 'defining your own math' section is for advanced users. So you don't need the pre-defined math for creating a model and the defining your own math is an advanced topic for creating your model. Maybe we need an intro and advanced section of each of creating, running, and analysing?
  4. This is provided as a timeline, but not in terms of setting up one model but in terms of a user progressing their capabilities in using the model. It is daunting for newcomers and we should address that.

Some ideas / questions that would be good to get your thoughts on @tud-mchen6:

  1. How would we clearly differentiate between pages that a user should not even think to look at until they've gone through intro/beginner parts of the docs?
  2. We could move "pre-defined math" to "Reference". It will be a bit hidden but maybe that's ok?
  3. What would you call "components" and "syntax"? We could split it out into pages on each "component" (constraints, variables, etc.) but there would be lots of overlap in content between those (they all have a "foreach" and "where" statement, etc.).
  4. Examples and tutorials are mostly showcasing the full modelling pipeline, so I can see why the "loading tabular data" page seems out of place - we should probably merge into the "creating a model" page, but that page is already quite long. to be honest, the logging and model objects are possibly out of place... So, where best to put these?