by strcat | 2025-06-07 14:29:11+00:00
If the web install guide only had to cover installing from macOS, ChromeOS and Android, it would be significantly simpler. Most of the complexity in the install guide is to work around issues with desktop Linux distributions. People do not need to read or understand the details about desktop Linux if they aren't using it. Similarly, people don't need to read or understand the details about installing a driver on Windows if they don't use Windows.

> There's a bunch of stuff in there about Linux... do I need Linux?

It's very clear about which browsers and platforms are officially supported at the top. Your complaint is essentially that we have not split up the guide based on install platform. That does make it more intimating, but doesn't have much impact on how easy it is to follow it.

> What's USB passthrough?

This is part of a paragraph telling people to avoid installing it from an OS in a virtual machine. This could be written in any guide about using a USB device. It's not specific to the web installer.

> Did I install my browser through Flatpak or Snap? How would I know? Did I need to understand the paragraph explaining in detail how carrier models lock users in? There's a bunch of stuff in there about Linux... do I need Linux? What's a sha256 hash and do I need to care?

People do not need to know about things only relevant to desktop Linux if they donj't use desktop Linux. Including instructions to work around desktop Linux problems doesn't make it harder for other people to install it. They simpler don't follow those parts of the guide because they don't use those things. It might make it less intimating to have it split up based on install platform but we haven't done that yet since we don't really want to have 5 or more web install pages instead of a single unified one. Another option would be selecting a platform with a drop-down menu and changing the guide based on it, but that's overly complex to maintain.

> It's not that this is impossible for non-IT-folks to grasp, but there's no chance that my parents are installing this on their phone.

Our experience shows that the vast majority of people can install it. The main reason someone couldn't is if English is their second language and they aren't capable of reading the instructions.

You're essentially asking for us to split out non-ChromeOS desktop Linux instructions from the guide due to how much of a mess working around it adds to the guide. That is something we could do along with splitting away Windows since it's also more complicated due to not having a USB driver. We don't think this would make it significantly easier to follow, but it would make it look easier. It is easy to follow the guide, especially on macOS, ChromeOS or Android. It's less easy on non-ChromeOS desktop Linux due to various issues with the overall platform, and the same for Windows to a lesser extent (installing a driver).

The reason the guide covers so much is because it covers all the common ways people have issues with their desktop OS or browser which impact following the guide. We added more information to the guide until people stopped needing help with installing it. People no longer typically need any help with it since we covered everything that comes up. Removing the information about troubleshooting and issues with platforms people use would make it harder and less accessible, not more. It's a good thing to have very detailed instructions covering all the edge cases and common issues.