Revamp: use a modular approach for tutorial materials #326
Conversation
|
This is a great suggestion @mbercx. I support this fully.
I would be a bit hesitant to rely too much on the Jupyter Notebooks, but maybe that is the best approach, given that we already have the notebook functionality embedded. It would certainly be nice for everyone to not have to cut and paste code snippets and that we could check that they actually work and produce the expected result.
For the specific how-to's I see no reason why these things can not be merged. I guess the how-to's would be a subset of the tutorial in this case. |
|
Thanks for your comments @espenfl!
I sort of understand your hesitation of using Jupyter notebooks for everything (but I'm not sure if it has the same root cause as mine ^^). I'm not able to explain it fully, but I'm not sure if it's best if users can just Shift+Enter their way through a notebook during a tutorial. I feel there will be less inclination for them to experiment a bit more with That said, I do favour using MyST markdown for writing our tutorials and documentation in general. Most people will be more familiar with Markdown, so they don't have to learn RestructuredText to start contributing to documentation. I also very much like the idea of making a notebook to explain how to do something, saving it in markdown using
I've given this some more thought this weekend, and think I have may have committed the sin of muddying the waters between Tutorials and How-to's. As is explained here, both serve different purposes, and should be kept separate. I think my suggestion to modularize the tutorial content may exactly blur the line between tutorial and how-to in a way that we shouldn't. Some examples of important differences:
So, I think the showcase I've built here would actually be best used for the "How-to" section on the documentation, rather than the tutorial page. This doesn't mean that we can't move to slightly more atomic hands-ons for tutorials that are easier to combine in ways that allow you to quickly build the material for a tutorials of different lengths. But I think the material has to be different, since they have different goals. This does mean that we have to maintain both, and that there will be some duplicated content between tutorials and how-to sections, but I fear that is simply unavoidable. |
|
I've updated the original post to reflect the latest version of my suggested changes to the tutorial page. Everything you need to read is now contained within that post. Pinging @ltalirz @giovannipizzi @csadorf for comments. |
Hmm. I could, but right now this draft PR doesn't really fix it yet. 😅 Plan would be to:
|
|
Thanks @mbercx! Let me start by saying that since I'm not the one doing the bulk of the work here, take this as input to consider and to incorporate as you see fit rather than as "change requests". Organisation of the repoUsing one branch per tutorial vs all tutorials in the It may be worth checking whether we are linking e.g. from aiida.net to web sites that become inaccessible with this change and see whether they can be fixed (or redirected as we do for the aiida-core docs). Tutorials vs howtos
As mentioned in the link you included, the main difference between tutorials and howtos is that tutorials are learning-oriented while howtos are problem-solving oriented.
In past tutorials I found particularly the last aspect somewhat underemphasized (we usually didn't have enough time to get to it) and I think it would be great to put some effort into this for this year's tutorial code-agnostic and code-flavored versionsYou anyhow suggest to keep this for the future, but I think this needs very careful consideration. The vast majority (if not all) of our audience still comes from the atomistic simulation community and it is easy to alienate them if we don't teach them how to use AiiDA for the types of problems they encounter in their daily work. I can understand the drive towards a code-agnostic approach for the "basic tutorial" in the docs where time is very limited and where we would otherwise need to explain how to install and set up a simulation code etc. This is not to say that one should not have two versions of the same module with different codes, but this then comes down to a question of maintenance effort, which essentially grows linearly with the number of codes (until we can include the common workflows next year ;-) ). Switching to MyST MarkdownSounds fine to me, I'm sure you've thought about it. Restructuring the contentIf I understand correctly, the "atomicity" of the individual modules has now again be relaxed somewhat, i.e. new instantiations of the tutorial would be allowed to do slight rearrangements of the structure, modification of the content etc. ? I believe this freedom will come in very handy. In terms of the actual top-level structure I have no specific suggestions other than to reintroduce the section numbering if possible. It makes it much easier to check where people are at during a tutorial. |
|
Thanks @ltalirz for your comments! I've responded to some points below.
I would add panels to the most recent tutorials, i.e. the ones we still want users to run. This way we have some control over which tutorials users wind up on, reducing the chance of them running a very old tutorial in the most recent versions. Also note that in case a user is running an old tutorial with the latest versions, we can always just point them to the latest version of the module. So maintaining the tutorials would focus on updating the most recent version (which can be tested automatically over time since we use MyST-NB).
Indeed, good point. I'm not sure if all tutorials materials need to be kept for posterity, though? For ones that I wouldn't add panels for, I guess we can just place them all in a
I agree most wholeheartedly! Re point 1: I think some parts of the tutorial try to explain a bit too much, but this is mainly the workflows ones, which I'll be working on. Re point 2: We should indeed add more exercises (especially for the writing workflows, again). This was raised by several participant from the 2020 tutorial, and these comments were converted into #334 by @ramirezfranciscof.
I agree, and for now the main modules will all remain Quantum ESPRESSO flavoured. "Over time" may be quite a bit of time, and especially for the events we organise for the Psi-k community we should always stick to DFT-code flavoured modules. I think for now I'll move the QE badge into the title, so it's clear that Quantum ESPRESSO flavoured, and add badges in the bottom panel to tutorials from other plugins whenever I find them or the plugin developers request it.
Hehe 😁 . I was actually considering doing a demo of the common-workflows (or at least a presentation) for this year's tutorial. It's quite impressive to see how easily you can run all these different workflows, so I think it will definitely grab the attention of the participants. Note that the provision of the code-flavoured tutorials is the responsibility of the plugin developers. I'll take care of the QE ones, of course, but will touch base with e.g. @espenfl on the VASP-flavoured versions of the tutorials. Creating a code-agnostic document that outlines the structure of the tutorial content (see #331) will be important to get the tutorials across different flavours to match as well as possible.
Of course, instances of the tutorial for events can make changes where necessary. The main goal is to have a single main tutorial page that is sorted by sections, and having the content on this page be as modular as possible so it's easier to throw together some modules for a tutorial of a specific size. |
@mbercx Yes, the formal analysis separating the two is interesting, but needs to be balanced by available resources and practical limitations otherwise. I believe in many cases that there are components in each that can be designed exactly the same, in particular code snippets etc. How those components are used and composed determine if it is a tutorial or a how-to in my view. The context. E.g. one can pick one option to be used in a tutorial, while in the how-to also include additional options and other ways of doing it. This can then also be linked in the tutorial at the given entry point and the user would then be immediately familiar with the context when approaching the how-to.
Absolutely. But let us try to minimize overlap. |
@mbercx Thanks a lot for working on the more general tutorial and how-to aspects. It is very important work that is easily missed or postponed indefinitely. I will try to contribute. Certainly to the VASP part, but also in general. Please let me know when you need something specific. |
I see - I think this is a very nice idea for involving plugin developers who are interested in contributing to the tutorial. |
@espenfl I agree. We can just have the how-to start with the option used in the tutorial, and then expand. This way we won't have to rewrite content. Linking to the how-to's from the tutorial module is a good idea, but perhaps at the beginning/end of the tutorial. A tutorial often start with what you will learn in the module anyways, maybe each bullet point will correspond to one how-to topic. In fact, maybe we should build the content of tutorial content in the context of how-to's. For example, the "Running your first calculation" module will teach you:
Each of these "topics" in the module can correspond to a how-to.
Thanks! Would be great if we could have VASP-flavoured versions of the running a calculation and running a workflow modules to link to with the badges. For the writing workflows modules, I will probably do this in a code-agnostic way, so you can also reuse these for your tutorials.
@ltalirz note that my intention was to have the code badges link to a corresponding module in the plugin documentation, so not have all tutorials in this repository. The only change we would do here is add the badges/links to the module panel, see for example the VASP badge here. |
This PR is a small showcase of how I would like to restructure the documentation materials. This post has been edited after giving the issue some more thought and discussion with others.
Motivation
The main reasons for adapting the tutorial structure/format are:
Because all the tutorials are visible in the sidebar when a user arrived on the landing page, it can be a bit overwhelming for users. @chrisjsewell already gave a helping hand here with the panels, but I think it would be better if the sidebar could be used to organise the tutorial content.
Since all the previously organised content is on the
masterbranch, all of it needs to be maintained. This includes any changes in switching sphinx versions or extensions, but also the content somewhat, since users do not always run the tutorials with the code versions specified.Because the tutorial material of a specific event is usually quite connected, it is difficult to piece together material for tutorials of different sizes and different audiences.
Since all of the material is written in RestructuredText, testing the material is a painstaking process with a lot of copy pasting that cannot be automated.
Suggested changes
Restructuring the content
The main idea is to organise the material of previous tutorials into standalone modules divided into sections (Fundamentals, calculations, workflows, etc...). Of course, each module will have some prerequisites. To organise these easily, I suggest the following:
The modules well be shown as
sphinx-panels, with the content growing progressively more advanced as the user goes down the page. An example can be found here:https://aiida-tutorials--326.org.readthedocs.build/en/326/sections/calculations/index.html
Switching to MyST Markdown
The tutorials will be written in MyST markdown, so they can be downloaded as Jupyter notebooks that can be easily run by the users and tested (automatically?). Previous content can be fairly easily converted using @chrisjsewell's RestructuredText to MyST Markdown converter.
Adding code-flavoured versions
Over time, we should make the tutorials on the
aiida-tutorialspage code-agnostic. They should use basic classes like theArithmeticAddCalculationto demonstrate the AiiDA concepts. However, each module panel can be decorated with little badges on the bottom that link to the corresponding tutorial on the tutorials page of that code (Quantum ESPRESSO, VASP, ...). Check out the showcase example to see what this would look like.Organising tutorial events
The material in the
masterbranch should be kept up to date with the latest version ofaiida-corewhenever possible. This will hopefully lead to fewer cases of users trying to execute material from previous versions with the latest version, running into issues.When we want to organise a tutorial, we just piece together the modules that we want to use, depending on the audience and the length of the tutorial. These will be put in a separate branch of the
aiida-tutorialsrepo, so each organised tutorial will have one branch that is kept as a reference, but no longer needs any maintenance.Tutorials versus How-to's
One important point that I failed to think about enough initially was the clear separation between "Tutorials" and "How-to's". As is explained here, both serve different purposes, and should be kept separate. My initial suggestion to modularize the tutorial content blurred the lines between tutorial and how-to in a way that we shouldn't. Some examples of important differences:
This doesn't mean that we can't move to slightly more atomic hands-ons for tutorials that are easier to combine in ways that allow you to quickly build the material for a tutorials of different lengths. But I think the material has to be different, since they have different goals. This does mean that we have to maintain both, and that there will be some duplicated content between tutorials and how-to sections, but I fear that is simply unavoidable.
In the latest commit, I've applied this modular approach in the context of tutorials as described above.