There are easy ways to improve the user experience when you have an existing website and you're installing Material on a new PC

[MaximilianKohler]

Here are the steps I went through and the subsequent trouble I had: #7752 (comment)

There may be some tunnel vision or lack of understanding of what's important to users if a developer considers this type of thing so "unimportant" that they go as far as to prevent a user from even discussing it. You can have the best software in the world, and if it's a pain in the ass to use or install then a lot of people are simply not going to bother with it, much less recommend it to others.

Squid may be right about the first "intro to python" part. I know I tried another way of installing python before and ran into problems, but I'm not sure if it was the method in the docs.

I had the Image Processing page https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/ in mind and was thinking the "Installation" page could be improved by mimicking those tabs for "macos", "windows", "linux". And I think python installation from the Windows Store is common enough that a short tip about adding the specific folder to Path would be an easy way to improve the documentation.

I'm not sure what you mean by that.

It seems like bad practice to say this and then close commenting as to not allow someone to further explain when it's clearly necessary.

A ctrl+f for "requirements" on the "installation" page gives 0 results. So if there's a "requirements" page, it's hidden away, just like the "image processing" page. I think there should be a link to it on the "installation" page. Eg: "You can review all the requirements here."

These are essential pages for this use case that are not obviously available when we're searching how to install Material [on a new PC].

I'm giving up a good amount of my time to try to improve the user experience for other people, in large part because what I experienced was unnecessarily difficult and time-consuming and can easily be remedied. This type of user feedback is essential to making improvements and creating a good UX. Locking the issue so that I couldn't even respond seems very excessive. It's quite off-putting for someone to be so dismissive of the issues people are experiencing, and so unreasonably opposed to taking input and making small changes that would greatly improve the user experience. Not to mention, that type of behavior/mentality is completely detrimental if your goal is to make an appealing product.

if you run the social plugin, and either didn't install the Python dependencies, or shared libraries that are necessary for the plugin to work, you're greeted with helpful error messages

Yes, one of those error messages landed me at the Troubleshooting section https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#troubleshooting. But that section makes no sense on its own. It only makes sense if you had started at the top of that page.

Thus, when I got there I was thoroughly confused about what "C:\msys64\ucrt64\bin" was, and the entire following instructions.
I ran the cairo-lookup-windows.py script and it didn't find the files anywhere (obviously, since they weren't installed yet).

There are definitely some easy ways this user flow can be improved.

I'm often not great with wording but I tried to write this as amiably as possible. I'm definitely grateful that this project exists. Thanks to everyone who works on it.

[squidfunk]

Thank you for your feedback. I locked the PR, because all has been said. You made your points and I, as a maintainer, made mine. We made a decision to not include your PR, please respect that. You are one of tens of thousands of users, and we need to balance things. More than often we need to say no to keep the project sharp. Additionally, as I explained in #7752 (comment), we detect the problematic situations during runtime and guide the user to a troubleshooting guide.

Locking the issue so that I couldn't even respond seems very excessive.

I've locked the issue because it's not the first encounter we had where I had to invest a lot of time of repeatedly making my point and you did not accept or respect our decision. It was going in that direction again. I wrote a long explanation, but I currently just can't invest more time into fighting with you over 1-2 sentences, as I need to invest my time into the bigger picture.

There are definitely some easy ways this user flow can be improved.

Definitely! We're actively working on much easier setup. Most of the unideal AX/DX comes from the limitations of MkDocs itself. We always try to find ways to work around this, and have something in the making that will be a game-changer in terms of AX/DX.

Now let's please put this discussion to a rest.

[MaximilianKohler]

So it would have been better if @kamilkrzyskow had not commented with details of the problem and suggested methods to fix it?

In my view, kamilkrzyskow's comment is the rational and expected response from a developer who cares about user experience. And his response will likely result in a simple and needed fix for this issue.

The amount of issues (2450) this project has is nowhere near overwhelming, and thus doesn't justify shutting down feedback like what I provided. Especially if developers are making money off the project.

[squidfunk]

Thank you again for your feedback and for taking the time to share your perspective. I understand your concerns and appreciate your effort to improve the user experience. However, as the maintainer, I have to weigh the needs and priorities of a broad user base while keeping the project manageable.

The decision to lock the previous discussion was not meant to dismiss your input but to signal that the matter has been sufficiently addressed from our end. Continuing the discussion won't lead to a different outcome, as we've already made a clear decision based on our goals and priorities for the project.

I kindly ask for your understanding and respect for this decision so we can focus on maintaining and improving the project for everyone. Constructive criticism is always welcome, but there are times when we must agree to disagree and move forward.

Thank you again for your contributions and for using Material for MkDocs.

[kamilkrzyskow]

Looking at the changes in #7752 I can sort of understand why it wasn't added, as this adds noise. A beginner Python / MkDocs user might try to read everything, and follow everything, even additional notes and have issues installing Cairo, and this might deter them from using the product altogether. Getting started guide should be as basic as possible to not overwhelm with features.

The getting started page recommends the usage of pip but also expects the user to know about it beforehand:

If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommend using docker.

I see this as a sort of cop-out, along the lines of "if you're using Python do it right, if you don't know what right means, then use docker, as you know how to use it, right? right?". The issue is that in Windows-land most people never run any commands in their life, so troubleshooting things like PATH probably never happened to them, and I don't see people using Docker all that much. Most people would not be as tenacious as Max in getting things to work.

Then again there are other blogging solutions which are more hands-on without any setup process, hard to say where to draw the line, as perhaps Material for MkDocs just isn't for everyone, there is configuration mkdocs.yml and deployment ci.yml all over, so not everybody wants to tinker with that.

The only true solution for a Windows user, to make it as seamless as possible, would be some sort of an executable. The issue with that is, most antivirus software flags executable Python-bundles. I don't know what sort of signing process would be required to resolve this. There could be also issues with the decision what to bundle, as this solution wouldn't work with dynamic plugins additions.

So a good mitigation for now would be to explicitly say "here is the guide we recommend to install Python and add it to PATH", because currently the only Python guide which is linked is under the "virtual environment" and this doesn't really suggest anything for a person not familiar with Python. A footnote would be good IMHO. Like a link to a video tutorial (this is the one I typically recommended over the years as it has both Mac and Windows and most importantly uses the correct standalone installer approach with PATH, however it's 7 years old, and this YouTuber also has a full VS Code Python setup guide for both Windows and Mac, however I never seen them in full, as I learned from other random resources).

---

As for the issue with Image Processing, instead of adding it to the getting started section. I would focus on improving the troubleshooting guide. We can't control the issues that a user could have during installation, but we can intercept the whole plugin initialization process, therefore I added the nice error messages with the link to instructions on what to do.

Yes, one of those error messages landed me at the Troubleshooting section https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#troubleshooting. But that section makes no sense on its own. It only makes sense if you had started at the top of that page.

The link points to the troubleshooting section, because it appears after the Cairo error, the previous step pip install "mkdocs-material[imaging]" was completed successfully, so there is no need to show the user the same thing again.

However, I can understand that "After following the installation guide above" inside the Cairo section, could be more explicit, that it's related to the MSYS2 environment, because a user would likely come to the troubleshooting guide from a non MSYS2 installation. 🤔

I ran the cairo-lookup-windows.py script and it didn't find the files anywhere (obviously, since they weren't installed yet).

The initial intention of the script was for the user to copy-paste them on their own and see the logic for how the PATH is being looked up, so I tried to make it as short as possible. Later it got changed into an automatic runnable online script, so perhaps it would help if it had more "prompts" for the user to see what is happening, because now it prints all of the data at once. 🤔

I initially wrote this for global system-wide usage with PowerShell, as initially the GTK3-Runtime installation was recommended as the way to install Cairo, and the global PATH was concerned. I see now that during the change to MSYS2 it seems like this part wasn't reevaluated, because the UCRT64 environment has its own PATH. I doubt that the script would find the Cairo MSYS2 installation from PowerShell. 🤔

So overall, I agree there needs to be some sort of fix-up to make the setup process for Windows users great again 🤘

[squidfunk]

So a good mitigation for now would be to explicitly say "here is the guide we recommend to install Python and add it to PATH", because currently the only Python guide which is linked is under the "virtual environment" and this doesn't really suggest anything for a person not familiar with Python. A footnote would be good IMHO. Like a link to a video tutorial (this is the one I typically recommended over the years as it has both Mac and Windows and most importantly uses the correct standalone installer approach with PATH, however it's 7 years old, and this YouTuber also has a full VS Code Python setup guide for both Windows and Mac, however I never seen them in full, as I learned from other random resources).

I'd be happy to swap out the link to the RealPython guide, since this seems to be a somewhat scammy site, as they sometimes try to force you to create an account (doesn't always happen, not sure why). If there's a better, more hands-on tutorial we can link from this box + a video, a PR is appreciated.

[MaximilianKohler]

A beginner Python / MkDocs user might try to read everything, and follow everything, even additional notes and have issues installing Cairo, and this might deter them from using the product altogether

Even though I have an MKdocs website already I think I'm largely a beginner. The steps listed on the "Image Processing" page were hassle-free. But you can easily avoid your concern with the proper wording. IE: If you plan to use xyz features then you'll also need to install these other dependencies.

Getting started guide should be as basic as possible to not overwhelm with features

The problem with that is the main "installation" page == "getting started guide". If you really don't want to add anything to the "getting started guide" then I'd suggest making an independent, more detailed installation page. As is, you have installation instructions on pages that have nothing to do with "installation". This is way more confusing for beginners IMO.

I see this as a sort of cop-out, along the lines of "if you're using Python do it right, if you don't know what right means, then use docker, as you know how to use it, right? right?". The issue is that in Windows-land most people never run any commands in their life, so troubleshooting things like PATH probably never happened to them, and I don't see people using Docker all that much. Most people would not be as tenacious as Max in getting things to work.

I agree completely. The "savior" here is that people looking into Material will probably look at the main MKDocs site & installation instructions first, and learn about installing Python there.

I don't think an executable is necessary, though I'd agree it would make things the most simple.

So a good mitigation for now would be to explicitly say "here is the guide we recommend to install Python and add it to PATH",

Agree!

The link points to the troubleshooting section, because it appears after the Cairo error, the previous step pip install "mkdocs-material[imaging]" was completed successfully, so there is no need to show the user the same thing again.

However, I can understand that "After following the installation guide above" inside the Cairo section, could be more explicit, that it's related to the MSYS2 environment, because a user would likely come to the troubleshooting guide from a non MSYS2 installation.

Yes, it had sent me there directly from the "installation" page, plus the pip install "mkdocs-material[imaging]" command that popped up in the console while I was installing Material. So I likely assumed those were the "previous steps" it was referring to.

FYI, another unnecessary step I went through (due to confusing steps) was to search my entire hard drive for the libcairo files and they were nowhere to be found (other than in some PortableApps.com folders).

It was necessary to install MSYS2 and then run the pacman -S mingw-w64-ucrt-x86_64-cairo command. Only then did the Troubleshooting section make sense.

The initial intention of the script was for the user to copy-paste them on their own and see the logic for how the PATH is being looked up

In my case I noticed a bunch of errors during the installation saying " is not in Path, consider adding it". But I didn't remember much about that and I was just following the installation instructions and figured that if I ran into problems after it was over I'll look them up.

so perhaps it would help if it had more "prompts" for the user to see what is happening

Yes, perhaps something about "Path" and then something about the Cairo Graphics section https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics. It should be pretty smooth with those two additions.

Thanks!

[kamilkrzyskow]

I have watched some tutorials on how to install Python or how to setup mkdocs-material (as they should include the former) to find the best one, and TBH they all have their own unique issues which make them not good enough to recommend in the docs IMHO 😞

The issues include:

• bad recording quality, e.g. there is some sort of static hiss sound, sound in only one ear, distracting music... etc.
• advertisements, e.g. "thanks XYZ for sponsoring the video" kind of thing, or advertising their other courses
• being too long
• incomplete information, e.g "just do that and it will work" without explaining the "why" or plain python installation without the part about virtual environments
• inaccurate information, e.g. assuming python -m venv venv is enough (without the source / activate part)

This video from Python Programmer is likely the "best", as it shows the "why" and isn't just "do that, then that", contains proper explanation of PATH, but it also has at least one of the issues above, like the sound, Replit ad, and lack of venv, so he points to an older video, which goes over the installation from the beginning again with venv, but without PATH...🙄

Apart from that, the Social plugin requires Cairo and MSYS2 has the up-to-date version of it, so even though a Windows user can start off with plain Python in the PowerShell they will be inevitably forced to set up MSYS2. And there is no real video tutorial for that to setup MSYS2 with Python, as it's mostly considered for C++ usage.

So I'm in a bind, as none of the "up-to-date" tutorials meet my standards of what would be a good thing to link from mkdocs-material.
Also most of the tutorials I've viewed were focusing on Windows or Mac without the mention of the other, so the docs would need to point to different videos for that.

I'll look into other written python installation guides, or even try out shorts to find a good one, but those aren't really good for keeping the users attention at bay 😆.

The "savior" here is that people looking into Material will probably look at the main MKDocs site & installation instructions first, and learn about installing Python there.

This also could be good. The MkDocs guide doesn't mention venv, however it might be sufficient to just point the user there, to make sure they go over the installation guide there first. Sometimes the best solutions are the simplest, however I will first go over other guides before recommending the one from MkDocs.

---

I'd suggest making an independent, more detailed installation page.

I don't think that's necessary TBH, as mentioned earlier the newcomer should have only one (preferably very short) installation process to get into playing with mkdocs-material. Then each new feature is opt-in and has their own "set up" process, including installation of dependencies for the Social plugin.

You make the case that a user, which had a longer brake, doesn't remember all of the "set up" processes for each plugin, and you suggest there should be a sort of "index page" with a summary with all of the possible dependencies each of the plugins might need.

My stance on that is, the errors, which occur if the setup is incomplete e.g. due to lacking dependencies, should guide the user to fix their issue, that's the use case of errors, if the error doesn't make it obvious what went wrong then the message should be improved.

So, given your comments, the best way forward is to improve the Troubleshooting guide to inform the user on what is missing, than to add extended docs on how to do it right "in the first place".