A question/idea about the installation guide

[sunnivin]

I have gone through the Step-by-step-guide. As a user with all the required tools already installed I had no problem with running the platform locally. But, I'm wondering if first-time (git and Docker) users might find the barrier of entry a bit high? Some comments/suggestions:

1. Would it be an idea to separate the different installation guides for different OS? It is possible to use tabs to make the text which is related to each OS clearer.

2. When the text mentions stuff like

Alternatively, open Docker desktop, find the containers tab, and shut them down them with the stop button.

Is it an idea to actually show some pictures of what the text suggests the user needs to do?

3. What about using admonitions for highlighting the text which is highlighted with NB like

NB! Note that the default values and input data we provide are sufficient for educational uses, but should not be considered high-quality model experiments. If your goal is to set up high-quality model experiments, you might want to modify or provide your own input data, set up long spin-up simulations to reach a steady-state, and think about model calibration and validation.

4. Do you recommend Git Bash as a general tool for all users? Mentioned in point 7 here. My experience with git bash on Windows is not so good. I really recommend (and prefer) the latest version of powershell as a Windows terminal.

If you (@evalieungh, @lasseke, @ka7eh) approve that these suggestions/changes make sense I can prepare a PR.

[ka7eh]

@sunnivin these are all good suggestions, and would be good improvements.
The part I cannot comment on is Git Bash vs Powershell: how different are the instructions for these tools? If they're too different, maybe we can include both?

Let's see what @evalieungh and @lasseke think because I'm not sure if making changes at this point affect the manuscript process.

[evalieungh]

Thanks for testing and for great suggestions, @sunnivin ! I had not seen the tabs functionality before, but it looks great. Separate guides for windows, mac and linux would be excellent and make it easier to be concise. Admonitions also seem like a very good idea. One thing to be aware of is that the Mkdocs-rendered webpage sometimes displays things a bit differently than markdown on GitHub (different markdown styles, maybe?). So we have to make sure the tabs and admonitions actually look like intended in the end.

About git bash vs powershell, I have no clear opinion but assumed git bash would be installed along with Git and therefore perhaps the most easily found by people who have never touched a terminal before. I just wanted to give a concrete example because only a few years back I would be very confused by a general instruction to "open a terminal".

Feel free to make a PR with suggestions! These are all minor/cosmetic improvements of the documentation and should not be a problem with the publishing process. I am working on some other minor changes to the documentation in a draft PR, but we can just resolve any conflicts if the changes should clash.

[sunnivin]

About git bash vs powershell, I have no clear opinion but assumed git bash would be installed along with Git and therefore perhaps the most easily found by people who have never touched a terminal before. I just wanted to give a concrete example because only a few years back I would be very confused by a general instruction to "open a terminal".

Natively, I'm not a Windows user. But, I have spent some time in my current job to become efficient with the tools that exist today. As I have understood git bash is an extra app for Windows. Struggling with paths and shells on Windows I really find modern Powershell (version > 7) in combination with the terminal-app to give a much better user experience. The native Windows shell, cmd, I find difficult. Because you can't use UNIX-commands in it. But, of course, this is a personal preference. I think that the guide should mention that git-bash needs to be installed as an app.

I will make a draft PR for you so you can take a look. My week is a bit busy at work, but I will try to do this ASAP.

[sunnivin]

But, a follow up question: I can't find you environment set-up for your python packages 😝 ?

As far as I can see you only set the mkdocs-version in the file .github/workflows/docs.yml? If the package version is not pinned it could explain why you get slightly different behavior when you develop locally and run the build with GitHub. If you think it is useful I can add a virtual environment so we lock the python dependencies for the docs? I usually use poetry for this, but if you have another preference I'm happy to adapt 😃

[lasseke]

Thanks so much for helping us with testing, @sunnivin :) and a very nice catch with the mkdocs versioning! I think this already became a bigger problem for us today: although everything worked fine before, the automated Docs gh actions failed with a permission error we had not seen earlier. Using a generic pip install for mkdocs could explain it.

The Python package management for the local containers is handled elsewhere, so could it be enough to hardcode the pip and mkdocs versions into the docs.yml for the workflow? Most users probably don't need this installed locally. But I also don't know much about gh actions, so feel very free to make a PR with a more sustainable solution! :)

[ziu1986]

I agree with @sunnivin that splitting the installation guide wrt OS would be helpful.