Draft for the landing page of the ece-teaching website

[LauWien]

This PR drafts the structure of the landing page for the new implemented ece-teaching website. It is intended to serve as a basis for discussion.

[LauWien]

Next PR the dev-ops and the structure of the landing page will be separate - sorry for that.

[khaeru]

• Separate directories ece-teaching/ and doc/ make sense when a repo contains both (a) a Python package and (b) its Sphinx documentation (the common use-case for Sphinx). But in this case, there is no (a), so:

  • ece-teaching/ can be deleted.
  • doc/ and even doc/source/ can be flattened to the top level.

  See message_doc for an existing example.

• Let's keep the organization as simple as possible until it needs to be more complicated.
  I think all the content can be condensed to a single page using different levels of ReST headings and a .. contents: directive. We don't need (yet)

  • an entire subtree for workshops…until there are several kinds of workshops that need a separate page, or separate pages each.
  • a separate page for the one line which is a URL to the code-and-tell repo.

  These just force the user to navigate back and forth instead of scrolling and getting a sense of the organization from a well-organized page.

• Please add some introductory text on the index page. Imagine the naïve or new user, and help them make sense of what they are looking at and how it is organized. For instance:

  The IIASA Energy, Climate, and Environment (ECE) Program and its staff are involved in many activities to support learning about model-based E/C/E research, especially using software and tools such as the MESSAGEix framework that we use ourselves.
  This page outlines and links to some of these activities & opportunities, and also the teaching & learning materials and resources used in those activities.

  Learning can take place in many ways, from self-directed study by individuals to for-credit courses at degree-granting institutions taught by a knowledgeable instructor.
  The right materials and venue for learning depends on factors including your current level of knowledge, learning goals, and time and resources you have available.
  The aim of this page is to clearly describe all the activities and materials so you can make an appropriate choice for your needs.

  …and then each section should have a sentence or two giving these details.

[danielhuppmann]

I guess that you don't want to commit the files in the _build folder, right?

[danielhuppmann]

Thank you @LauWien!

One question to @volker-krey and @khaeru before merging this PR: what should be the organizing principle of the section External contributions by ECE staff - by item or by person? The by-item list might get quite long quickly, so having a sub-page (alphabetically sorted) for each person that wants to present their external teaching could be more "future-proof". Thoughts?

[khaeru]

Hmm...well, I think we should categorise or sort by things like the duration/extent (single lecture to seminar to full credit course); level (beginner to advanced); whether the item is recurring (so a reader might possibly think to join a next time) or was one-off and it's just the material shared; maybe closed and open. Maybe a few subsections to collect for now.

The idea is that the reader can navigate according to what they need. Since some of us present at both ends of this scale (from long to short) and everything between, the per-person organization would sort of scatter similar kinds of material across multiple pages (Daniel's courses and Behnam's course(s) on different pages; Paul's short talks and Volker's short talks on different pages; etc.). That makes it hard for a reader to see all the options of (for instance) ~3 hours duration, and choose one that seems suitable.

I also wouldn't know where to put materials that have been presented or jointly developed by 2 or more people.

[volker-krey]

Thanks for setting this up. Regarding the question of how to structure the material, I would agree with Paul that organizing by lecturer is probably not very useful for the readers of these pages. I would argue that distinguishing between internal and external contributions is also not too meaningful for readers.
The category Workshops and tutorials makes a lot of sense to me and I would see MESSAGEix and GAINS workshops appear here. The Code-and-Tell category also makes sense for a technical audience. In addition, we may want to have a section for broader classes, maybe under the heading of Systems Analysis and Modeling Classes as they often go beyond just modeling and a section for single-lecture type of teaching, e.g. as part of a summer school or a single lecture as part of a broader course, which is often on a specific topic (e.g., recent NGFS contribution by Bas, Jihoon and Daniel).

[volker-krey]

One more comment: I would be in favor of having a separate subpage for the MESSAGEix workshop as these cover a series of lectures, including video tutotrial(s) which seems too much to me to include on the main page.

[LauWien]

Thank you all for your input!
If I understood correctly I would then set up the structure as follows:

• Workshops and tutorials
  -- sub-page: MESSAGEix
  -- sub-page: GAINS (assuming this covers also a series of lectures, and to be align with the layout)
• Code-and-Tell
• Systems Analysis and Modeling Classes

I guess the sorting of the material of the last bullet point still needs to be discussed and should be decided at the latest when more learning material will get uploaded, what do you think?
The following as mentioned by @khaeru and maybe other sorting options are possible:

• duration/extent (single lecture to seminar to full credit course);
• level (beginner to advanced);
• recurrence;
• closed/open.

[volker-krey]

Thanks @LauWien. I would suggest to hide GAINS initially as I am not sure on which timescale that contribution will materialize. And adding the single lectures from the start might be good as there is quite a bit of material in that category.

[volker-krey]

One more thought: I am wondering whether information on level, duration etc. can be provided via tags/labels, similar to those used in GitHub issues.

[LauWien]

One more thought: I am wondering whether information on level, duration etc. can be provided via tags/labels, similar to those used in GitHub issues.

That sounds interesting! Also then possibly being able to sort by those tags.. I will have a look and get back to you!

I created an issue #3 for this.

[danielhuppmann]

To me, this looks like a very decent starting point. Improvements to the individual sections can then be made as part of ongoing additions of new content.