Doc: improve referencing to aiida-tutorials

[khsrali]

Fixes #6287

Good morning everyone!

Following our discussion on issue #6287 about discoverability of aiida-tutorials I collected our ideas and made the following changes in documentation. I tried to keep changes minimal and inline with current formatting.

• Created proper referencing to tutorials.
• A brief explanation is provided for new users to ensure that they follow the basic tutorial first and can easily navigate to the aiida-tutorials.
• Added an external link to cheat sheet.

Please feel free to join a review, and suggest your changes!
For simplicity, I took screenshot of the compilation and painted with red marker to show my changes:

To dos:

• demos - where would it go, and which one of the many should it include?
• cheat sheet: maybe a better placing? one could put it below tutorials..

[GeigerJ2]

Hi @khsrali, thanks for creating the PR! To add some points here that came up during our discussion right now:
One thing I always found confusing about the readthedocs landing page is that the main panels are almost mirrored in the top bar, but not quite. In the latter, "Tutorial" is missing, while "Getting Started" is called "Introduction". Clicking on "Getting Started" leads to a subsection of "Introduction", and so does clicking on "Tutorial", however, the resulting page is called "Basic Tutorial".

Therefore, I propose to make everything consistent, i.e. naming the first panel the same as the first item in the top bar (e.g. "Introduction"), and have them both point to the same page. Further, moving the "Basic Tutorial" out of the "Introduction" and into its own page. We're still not sure where to best put the cheat sheet. Possibly as a separate panel on the landing page, as I proposed in issues #6287 and #6290 (though, we might not have enough space in the top bar to include eight items...). Alternatively, keeping just one "Tutorials" page, as @khsrali did in this PR, which then points to the "Basic" and "Advanced" Tutorials, where we could also add the cheat sheet.

[sphuber]

Thanks a lot @khsrali .

I agree with @GeigerJ2 that it would be good to make the panel titles line up with the top bar navigation. I am not sure if we should rename the "Getting started" tile to "Introduction", though. As a new prospective user, typically I immediately search for something to get started. Seeing "Introduction" doesn't suggest to me immediately that I can find it there. It more seems like I would find a long-winded text like an academic paper. So I would be tempted to rename "Introduction" to "Getting started".

Looking at the subsections of introduction.rst, we would have to move tutorial.md to its own subdirectory (with its own panel). The "advanced configuration" can just be part of getting started, as well as the troubleshooting (at least the parts that are specific to installation/configuring). That leaves the "What is AiiDA" section. I am not sure where to put this. Putting it on the main page might make the main page too crowded perhaps? But giving it its own panel also seems like overkill. Thoughts?

Regarding the design of the tutorials page: the advanced tutorials panel seems a bit off. It is now just a page that contains a link to aiida-tutorials, so the page is a bit superfluous. Why not make it link directly to aiida-tutorials. But also, I am not sure they are really advanced tutorials. If the idea is that we will be adding more tutorials directly in aiida-core's docs, similar to the basic one, maybe we don't have an entire panel for the aiida-tutorials link, but just have a simple paragraph with a link, explaining that that contains additional info for those interested.

[khsrali]

Thank you @sphuber for noticing and your comments.

I agree with @GeigerJ2 that it would be good to make the panel titles line up with the top bar navigation.

I agree with that too, I think it's a good idea.

That leaves the "What is AiiDA" section. I am not sure where to put this. Putting it on the main page might make the main page too crowded perhaps? But giving it its own panel also seems like overkill. Thoughts?

I also think it's a good idea to put it on the main page; it wouldn't seem crowded to me. It could either replace the short introductory paragraph of AiiDA on top or go below the panels just above "How to cite".

Regarding the design of the tutorials page: the advanced tutorials panel seems a bit off. It is now just a page that contains a link to aiida-tutorials, so the page is a bit superfluous. Why not make it link directly to aiida-tutorials.

You are actually right, that would have make more sense. But I thought maybe it would be nice to add a bit of explanation about where that link is going **--see below

If the idea is that we will be adding more tutorials directly in aiida-core's docs, similar to the basic one, maybe we don't have an entire panel for the aiida-tutorials link, but just have a simple paragraph with a link, explaining that that contains additional info for those interested.

Well the idea was simply to make aiida-tutorials more discoverable, I think these tutorials (basic and "advanced") are designed thoughtfully as they are. So maybe there is no need to add more material in aiida-core documentation, but rather just to make tutorials easy to find. I understand they are well linked in aiida-website, but personally, aiida-core documentation was the first place I went, so that's why I felt a need to link these beautiful tutorials there as well.
In fact, now that I think about it, maybe it's even better to link aiida.net as well, just to make sure these domains are well linked to each other. Such that those who for aiida-core documentation for the first time could also easily navigate to aiida.net.

Actually, I tried to give a short explanation with links, just as you say, but then it tuned into the advanced tutorials page **. If we completely remove the explanation and do not call it an "advanced" tutorial, then having Basic tutorials and an external link named 'tutorial' (?) would be confusing. On the other hand, if we keep the explanation, that may require a page, I suppose. Comments are welcome on how to do it.

[sphuber]

Actually, I tried to give a short explanation with links, just as you say, but then it tuned into the advanced tutorials page **. If we completely remove the explanation and do not call it an "advanced" tutorial, then having Basic tutorials and an external link named 'tutorial' (?) would be confusing. On the other hand, if we keep the explanation, that may require a page, I suppose. Comments are welcome on how to do it.

I agree that having only the basic tutorial and then the link is not ideal. I think we can and probably should have more generic tutorials on the main documentation. That is why I would organize it as the tutorials.rst page just being a list of tutorials. For now it will just contain the first "basic" tutorial (maybe should be renamed) and then we can add more later. I think the tutorials on aiida-tutorials are not going to be very useful in the long run. Reason is that there are multiple versions, each one corresponding to the actual physical tutorial during which they were represented. They are therefore also going stale, as they are not updated. I think the relevant tutorials should simply be on the AiiDA docs. And the link to aiida-tutorials can be a simple link somewhere on the page, saying that those are additional tutorials that were given in the past that may be useful.

[khsrali]

generic tutorials on the main documentation. That is why I would organize it as the tutorials.rst page just being a list of tutorials. For now it will just contain the first "basic" tutorial (maybe should be renamed) and then we can add more later.

Alright, then tutorials.rst part is already sort of done -- the tutorials page.

I think the tutorials on aiida-tutorials are not going to be very useful in the long run. Reason is that there are multiple versions, each one corresponding to the actual physical tutorial during which they were represented. They are therefore also going stale, as they are not updated. I think the relevant tutorials should simply be on the AiiDA docs. And the link to aiida-tutorials can be a simple link somewhere on the page, saying that those are additional tutorials that were given in the past that may be useful.

Many thanks for insights. To summarize, what I understood from @GeigerJ2 and @sphuber suggestions:

• to remove the "Advance" tutorial page and simply put a link and a short explanation, right in the tutorial page.
• rename both "advanced" and "basic " to something else
• make room for more panels on the tutorial page to transfer useful docs from tutorials to there, in future. -- we can open a separate PR regarding that.
• do not collapse the tutorials category (drop down) on the left panel.
• make the left panel titles line up with the top bar navigation.
• "What is AiiDA" section, perhaps to move to the home page.

Please don't hesitate to add, if I forgot any. Otherwise, I'll turn this PR into a draft, implement these changes, and make a request again.
Thank you,

[sphuber]

Great summary @khsrali thanks a lot. Before you do anything, in order to prevent any unnecessary/double work, maybe we discuss this tomorrow with the rest of the team during the coding days. If they agree then you can go ahead and implement the changes, but would be good to have as much eyes on the suggestions for the docs as possible, and I want to prevent you have to keep changing things around. Would that work for you?

[khsrali]

Great, nice to let me know @sphuber ! it's best to discuss it first.

[unkcpz]

I think having tutorial as a head navigator is a super great idea, I did participate in a talk about technical documentation authoring and it sells their rule https://diataxis.fr/. As I know the community like jupyter having some of their tool documentation move to follow this rule. I think we are more or less follow the rule. The tutorial is a pillar of the rule and something the new user usually want to find after they heard about the tool and want to get start.
But after adding the "tutorial" the head navigators are too many, the "internal archetecture" goes into the folded "More" tab, which I think it is fine.
If we just follow this diataxis rule, we probably what to change the name "topics" -> "explanation". I think "topic" is a bit confusing.

The "advanced configuration" can just be part of getting started, as well as the troubleshooting

Fully agree!

That leaves the "What is AiiDA" section. I am not sure where to put this. Putting it on the main page might make the main page too crowded perhaps? But giving it its own panel also seems like overkill. Thoughts?

Remind me of a discussion https://aiida.discourse.group/t/section-what-is-aiida-is-not-easy-to-find/44

To be honest, I don't like the index page, it is gives very little information about what AiiDA is and how it is great. I think some content of "What is AiiDA" needs to go to the index page. I also didn't see the point that the introduction tab is simply a navigator link to more things. Moreover, the panel tabs (in the figure below) in the index page seems useless (if it is a "get start" it get user start, if it is a "Explanation" it explain things) and occupy too many space of the important index page.
If technically not hard to do, I'd suggest make all these panel as navigator panal on the left side, so user can directly start navigate on the sections and have an bird-eye view on the documentation. We can even add more as in their that user can one step jump into the page for the specific thing, such as "examples" where can put some workflows for different domains as what had by other workflow engines (but it requires maintenance on the example with the plugins provide the functionalities, so require more discussion on this, I'll create an issue if someone think this is a good idea).
Then with the space left out if we agree on removing the panel tabs, we can put more information from "What is AiiDA" on the index page.

[khsrali]

Thank you, @unkcpz for your comment.

https://diataxis.fr/.

Very interesting! good to know.

I think some content of "What is AiiDA" needs to go to the index page.

As we discussed today in AiiDA-core wrap up, I'll take care of this and update the PR.

I think the relevant tutorials should simply be on the AiiDA docs.

And with this comment of @sphuber we can certainly do a separate PR for that later on.

[khsrali]

Alright, changes noted have been applied. Main changes are:

• "What is AiiDA?" now appears with it's content in introduction pages
• "Advanced configuration" move under Getting started, as you all suggested last time
• aiida-tutorials is only mentioned as "archive-tutorials", without having a separate page
• I think now, tutorial page is ready, to have more useful materials to be taken from aiida-tutorials,later on. At that point we can change it's name from "basic" to something else.

I appreciate if @unkcpz if you can have look for review.
Thanks

[sphuber]

Thanks @khsrali . The docs build is failing, which makes it more difficult to review the changes. Looking at the logs, there is at least this warning:

/home/docs/checkouts/readthedocs.org/user_builds/aiida-core/checkouts/6288/docs/source/intro/about.rst:5: WARNING: duplicate label intro:about, other instance in /home/docs/checkouts/readthedocs.org/user_builds/aiida-core/checkouts/6288/docs/source/intro/about.rst

[khsrali]

Thanks @khsrali . The docs build is failing, which makes it more difficult to review the changes. Looking at the logs, there is at least this warning:

Thanks @sphuber,
yes there was an issue with .. include:: about.rst: which lead to defining intro:about twice.
Anyhow, I think about.rst is not needed anymore, since all it's content is moved into intro/index.rst
Now all is ok.

[GeigerJ2]

Hi @khsrali, thanks for taking care of this! To me, all looks good. The only suggestion I have would be to call it "Tutorial Archive", which sounds more like an ancient mystery box that I would like to click on and discover :D (otherwise, "Archived tutorials?)

Just to mention it here, I have an open PR to update the current aiida-tutorials to aiida-core v2.5.1, so we should soon be able to start migrating suitable, general parts from there to the main docs 👍

[sphuber]

Thanks @khsrali . Some final changes requested and then we can merge

[sphuber]

Since we are planning on adding multiple tutorials, I would actually take this opportunity to create the tutorials directory and rename this page to tutorials/index.rst. Then move the current intro/tutorial.md to tutorials/basic.md.

[khsrali]

Agreed, makes sense..

[khsrali]

Thank you @sphuber for your good suggestion. I applied this change.
However, tutorial without toctree feels very weird, especially now that it has its own directory.
please check now with the new commit, and let me know if you agree.

[khsrali]

ok I was trying to squash commit, apparently it's useless when working on a fork..

[sphuber]

ok I was trying to squash commit, apparently it's useless when working on a fork..

It doesn't matter whether the branch is on a fork. I squashed the branch for you after updating it. I see that you have renamed your fork aiida-core--forked. Note that this renaming with the --forked suffix is not necessary and also not usual. Since your fork is inside the namespace of your Github user, it has a unique address even if you keep its name to be aiida-core.

I typically set the original repo up as the remote origin in git and then add my fork as fork. For example:

$ git remote add origin [email protected]:aiidateam/aiida-core
$ git remote add origin fork [email protected]:sphuber/aiida-core
$ git remote -v
fork	[email protected]:sphuber/aiida-core (fetch)
fork	[email protected]:sphuber/aiida-core (push)
origin	[email protected]:aiidateam/aiida-core (fetch)
origin	[email protected]:aiidateam/aiida-core (push)

To squash the commits on your branch, I did the following

git remote add khsrali [email protected]:khsrali/aiida-core--forked
git fetch --all # Update all data from remotes
git checkout Doc--proper-referencing-to-tutorials  # Check out your branch
git merge origin/main  # Merge latest changes from `main` so your branch is up to date
git reset --soft origin/main  # Reset the state to `origin/main` but soft, so keep the changes locally

Now if you go git status you will see all the changes you made in your branch as staged changes. You can then simply git commit to turn them into a single commit.

Hopefully that helps

[sphuber]

Thanks a lot @khsrali , all good to go!

[khsrali]

Thanks a lot @sphuber for merging and your very useful comment!